@xiashe/sdk 0.1.0

package/README.md

@@ -0,0 +1,13 @@
+# @xiashe/sdk
+
+Shared Node SDK for XiaShe CLI, Agent Gateway clients, local agents, and operational scripts.
+
+The SDK wraps:
+
+- Convex auth and user-scoped function calls.
+- Skill catalog and background install jobs.
+- Claw connection pairing helpers.
+- Agent Gateway claim, heartbeat, task, and MCP calls.
+- Unified file upload/listing.
+
+It stores local CLI state in `~/.xiashe/config.json` by default.

package/index.mjs

@@ -0,0 +1,845 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile, stat } from 'node:fs/promises';
+import os from 'node:os';
+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 DEFAULTS = {
+  cn: {
+    market: 'cn',
+    locale: 'zh-CN',
+    convexUrl: 'https://api.xiashe.chat',
+    actionsUrl: 'https://actions.xiashe.chat',
+    mcpUrl: 'https://actions.xiashe.chat/mcp/xiashe',
+    agentClaimUrl: 'https://actions.xiashe.chat/agent-gateway/claim',
+    relayUrl: 'https://relay.xiashe.chat'
+  },
+  global: {
+    market: 'intl',
+    locale: 'en',
+    convexUrl: 'https://adept-porcupine-970.convex.cloud',
+    actionsUrl: 'https://actions.agentpie.app',
+    mcpUrl: 'https://actions.agentpie.app/mcp/xiashe',
+    agentClaimUrl: 'https://actions.agentpie.app/agent-gateway/claim',
+    relayUrl: 'https://relay.agentpie.app'
+  }
+};
+
+const DEFAULT_ENV = process.env.XIASHE_DEFAULT_ENV === 'global' || process.env.XIASHE_DEFAULT_ENV === 'intl'
+  ? 'global'
+  : 'cn';
+const DEFAULT_PRODUCT_NAME = process.env.XIASHE_PRODUCT_NAME || (DEFAULT_ENV === 'global' ? 'AgentPie' : 'XiaShe');
+const DEFAULT_CLI_NAME = process.env.XIASHE_CLI_NAME || (DEFAULT_ENV === 'global' ? 'agentpie' : 'xiashe');
+const CONFIG_DIR = process.env.XIASHE_CONFIG_DIR || path.join(os.homedir(), DEFAULT_ENV === 'global' ? '.agentpie' : '.xiashe');
+const CONFIG_PATH = process.env.XIASHE_CONFIG_PATH || path.join(CONFIG_DIR, 'config.json');
+const DEFAULT_PROFILE = 'default';
+const HTTP_TIMEOUT_MS = 20_000;
+
+export class XiasheError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'XiasheError';
+    this.code = options.code || message;
+    this.status = options.status;
+    this.details = options.details;
+  }
+}
+
+export function configPath() {
+  return CONFIG_PATH;
+}
+
+export function configDir() {
+  return CONFIG_DIR;
+}
+
+export function normalizeBaseUrl(value) {
+  return String(value || '').trim().replace(/\/+$/, '');
+}
+
+export function nowIso(value = Date.now()) {
+  if (!value) return '';
+  return new Date(Number(value)).toISOString();
+}
+
+export function createIdempotencyKey(prefix, parts = []) {
+  const hash = createHash('sha256')
+    .update([prefix, ...parts.map((part) => String(part ?? ''))].join('\n'))
+    .digest('hex')
+    .slice(0, 24);
+  return `${prefix}:${hash}`;
+}
+
+export function inferMime(filePath) {
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith('.png')) return 'image/png';
+  if (lower.endsWith('.jpg') || lower.endsWith('.jpeg')) return 'image/jpeg';
+  if (lower.endsWith('.gif')) return 'image/gif';
+  if (lower.endsWith('.webp')) return 'image/webp';
+  if (lower.endsWith('.pdf')) return 'application/pdf';
+  if (lower.endsWith('.json')) return 'application/json';
+  if (lower.endsWith('.csv')) return 'text/csv';
+  if (lower.endsWith('.md')) return 'text/markdown';
+  if (lower.endsWith('.txt')) return 'text/plain';
+  return 'application/octet-stream';
+}
+
+function freshConfig() {
+  const defaults = DEFAULTS[DEFAULT_ENV];
+  return {
+    profile: DEFAULT_PROFILE,
+    profiles: {
+      [DEFAULT_PROFILE]: {
+        name: DEFAULT_PROFILE,
+        market: defaults.market,
+        locale: defaults.locale,
+        convexUrl: defaults.convexUrl,
+        actionsUrl: defaults.actionsUrl,
+        mcpUrl: defaults.mcpUrl,
+        agentClaimUrl: defaults.agentClaimUrl,
+        relayUrl: defaults.relayUrl
+      }
+    }
+  };
+}
+
+export async function readConfig() {
+  if (!existsSync(CONFIG_PATH)) {
+    return freshConfig();
+  }
+  const raw = await readFile(CONFIG_PATH, 'utf8');
+  try {
+    const parsed = JSON.parse(raw);
+    const base = freshConfig();
+    const profiles = { ...base.profiles };
+    for (const [name, profile] of Object.entries(parsed.profiles || {})) {
+      profiles[name] = {
+        ...base.profiles[DEFAULT_PROFILE],
+        ...(profile || {}),
+        name
+      };
+    }
+    return {
+      ...base,
+      ...parsed,
+      profiles
+    };
+  } catch (error) {
+    throw new XiasheError(`Invalid ${DEFAULT_PRODUCT_NAME} config JSON at ${CONFIG_PATH}`, { code: 'CONFIG_INVALID_JSON', details: error });
+  }
+}
+
+export async function writeConfig(config) {
+  await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  await writeFile(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  return config;
+}
+
+export async function getProfile(name) {
+  const config = await readConfig();
+  const profileName = name || config.profile || DEFAULT_PROFILE;
+  return {
+    config,
+    profileName,
+    profile: {
+      ...freshConfig().profiles[DEFAULT_PROFILE],
+      ...(config.profiles?.[profileName] || {})
+    }
+  };
+}
+
+export async function updateProfile(name, patch) {
+  const config = await readConfig();
+  const profileName = name || config.profile || DEFAULT_PROFILE;
+  config.profiles = config.profiles || {};
+  config.profiles[profileName] = {
+    ...(config.profiles[profileName] || {}),
+    ...patch,
+    name: profileName
+  };
+  return writeConfig(config);
+}
+
+export async function useProfile(name) {
+  const config = await readConfig();
+  config.profile = name || DEFAULT_PROFILE;
+  config.profiles = config.profiles || {};
+  config.profiles[config.profile] = config.profiles[config.profile] || { name: config.profile };
+  return writeConfig(config);
+}
+
+export async function useEnvironment(envName, profileName) {
+  const normalized = String(envName || '').toLowerCase();
+  const defaults = normalized === 'global' || normalized === 'intl' ? DEFAULTS.global : DEFAULTS.cn;
+  await updateProfile(profileName, {
+    market: defaults.market,
+    locale: defaults.locale,
+    convexUrl: defaults.convexUrl,
+    actionsUrl: defaults.actionsUrl,
+    mcpUrl: defaults.mcpUrl,
+    agentClaimUrl: defaults.agentClaimUrl,
+    relayUrl: defaults.relayUrl
+  });
+  return defaults;
+}
+
+function envProfile(profile) {
+  const defaults = DEFAULTS[DEFAULT_ENV];
+  const actionsUrl = normalizeBaseUrl(process.env.XIASHE_ACTIONS_URL || process.env.AGENTPIE_ACTIONS_URL || profile.actionsUrl);
+  const mcpUrl = process.env.XIASHE_MCP_URL || process.env.AGENTPIE_MCP_URL || (actionsUrl ? `${actionsUrl}/mcp/xiashe` : profile.mcpUrl);
+  const agentClaimUrl =
+    process.env.XIASHE_AGENT_CLAIM_URL || process.env.AGENTPIE_AGENT_CLAIM_URL || (actionsUrl ? `${actionsUrl}/agent-gateway/claim` : profile.agentClaimUrl);
+  return {
+    ...profile,
+    convexUrl: process.env.XIASHE_CONVEX_URL || process.env.AGENTPIE_CONVEX_URL || profile.convexUrl,
+    actionsUrl,
+    mcpUrl,
+    agentClaimUrl,
+    relayUrl: process.env.XIASHE_RELAY_URL || process.env.AGENTPIE_RELAY_URL || profile.relayUrl,
+    market: process.env.XIASHE_MARKET || process.env.AGENTPIE_MARKET || profile.market || defaults.market,
+    locale: process.env.XIASHE_LOCALE || process.env.AGENTPIE_LOCALE || profile.locale || defaults.locale,
+    session: {
+      ...(profile.session || {}),
+      ...(process.env.XIASHE_USER_ID || process.env.XIASHE_SESSION_TOKEN
+        ? {
+            userId: process.env.XIASHE_USER_ID || profile.session?.userId,
+            sessionToken: process.env.XIASHE_SESSION_TOKEN || profile.session?.sessionToken
+          }
+        : {})
+    },
+    agent: {
+      ...(profile.agent || {}),
+      ...(process.env.XIASHE_RUNTIME_TOKEN
+        ? {
+            runtimeToken: process.env.XIASHE_RUNTIME_TOKEN
+          }
+        : {})
+    }
+  };
+}
+
+function normalizeConvexError(error) {
+  const message = error instanceof Error ? error.message : String(error || '');
+  if (/fetch failed|failed to fetch|network request failed|econnrefused|enotfound|eai_again/i.test(message)) {
+  return new XiasheError('Unable to reach Convex deployment.', {
+      code: 'CONVEX_NETWORK_UNAVAILABLE',
+      details: error
+    });
+  }
+  if (/timed out|timeout|abort/i.test(message)) {
+    return new XiasheError('Convex request timed out.', {
+      code: 'CONVEX_TIMEOUT',
+      details: error
+    });
+  }
+  return error;
+}
+
+export async function loadProfile(options = {}) {
+  const { config, profileName, profile } = await getProfile(options.profile);
+  const cleanOptions = Object.fromEntries(
+    Object.entries(options).filter(([key, value]) => key !== 'profile' && value !== undefined && value !== '')
+  );
+  return {
+    config,
+    profileName,
+    profile: envProfile({
+      ...profile,
+      ...cleanOptions
+    })
+  };
+}
+
+async function withTimeout(promiseFactory, timeoutMs = HTTP_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await promiseFactory(controller.signal);
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw new XiasheError('Request timed out.', { code: 'REQUEST_TIMEOUT' });
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function postJson(url, body, options = {}) {
+  const timeoutMs = options.timeoutMs || HTTP_TIMEOUT_MS;
+  const headers = options.headers || {};
+  const response = await withTimeout(
+    (signal) =>
+      fetch(url, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          ...headers
+        },
+        body: JSON.stringify(body ?? {}),
+        signal
+      }),
+    timeoutMs
+  );
+  const text = await response.text();
+  let payload = {};
+  try {
+    payload = text ? JSON.parse(text) : {};
+  } catch {
+    throw new XiasheError(`Bad JSON response from ${url}`, { code: 'HTTP_BAD_JSON', status: response.status });
+  }
+  if (!response.ok) {
+    throw new XiasheError(payload.error || payload.message || `HTTP ${response.status}`, {
+      code: payload.error || `HTTP_${response.status}`,
+      status: response.status,
+      details: payload
+    });
+  }
+  return payload;
+}
+
+export async function mcpCall(mcpUrl, runtimeToken, method, params = {}, timeoutMs = HTTP_TIMEOUT_MS) {
+  const payload = await postJson(
+    mcpUrl,
+    {
+      jsonrpc: '2.0',
+      id: `${Date.now()}-${Math.random().toString(16).slice(2)}`,
+      method,
+      params
+    },
+    {
+      timeoutMs,
+      headers: runtimeToken ? { authorization: `Bearer ${runtimeToken}` } : {}
+    }
+  );
+  if (payload.error) {
+    throw new XiasheError(payload.error.message || 'MCP error.', {
+      code: payload.error.code || 'MCP_ERROR',
+      details: payload.error
+    });
+  }
+  return payload.result;
+}
+
+export function decodeMcpToolResult(result) {
+  const text = result?.content?.find?.((item) => item?.type === 'text')?.text;
+  if (typeof text !== 'string') {
+    return result;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { text };
+  }
+}
+
+export class XiasheClient {
+  constructor(profile, options = {}) {
+    this.profile = envProfile(profile || {});
+    this.profileName = options.profileName || DEFAULT_PROFILE;
+    this.timeoutMs = options.timeoutMs || HTTP_TIMEOUT_MS;
+    this._convex = null;
+  }
+
+  static async fromConfig(options = {}) {
+    const loaded = await loadProfile(options);
+    return new XiasheClient(loaded.profile, {
+      profileName: loaded.profileName,
+      timeoutMs: options.timeoutMs
+    });
+  }
+
+  convex() {
+    if (!this.profile.convexUrl) {
+      throw new XiasheError('Missing Convex URL. Run `xiashe config set convexUrl <url>` or pass --convex-url.', {
+        code: 'CONVEX_URL_REQUIRED'
+      });
+    }
+    if (!this._convex) {
+      this._convex = new ConvexHttpClient(this.profile.convexUrl);
+    }
+    return this._convex;
+  }
+
+  authArgs(extra = {}) {
+    const userId = this.profile.session?.userId;
+    const sessionToken = this.profile.session?.sessionToken;
+    if (!userId || !sessionToken) {
+      throw new XiasheError(`Not signed in. Run \`${DEFAULT_CLI_NAME} login --email <email> --password <password>\` first.`, {
+        code: 'AUTH_REQUIRED'
+      });
+    }
+    return {
+      requesterUserId: userId,
+      sessionToken,
+      ...extra
+    };
+  }
+
+  async query(ref, args = {}) {
+    try {
+      return await this.convex().query(ref, args);
+    } catch (error) {
+      throw normalizeConvexError(error);
+    }
+  }
+
+  async mutation(ref, args = {}) {
+    try {
+      return await this.convex().mutation(ref, args);
+    } catch (error) {
+      throw normalizeConvexError(error);
+    }
+  }
+
+  async action(ref, args = {}) {
+    try {
+      return await this.convex().action(ref, args);
+    } catch (error) {
+      throw normalizeConvexError(error);
+    }
+  }
+
+  async signInWithPassword(email, password) {
+    return this.mutation(api.auth.signInWithPassword, { email, password });
+  }
+
+  async registerWithPassword(email, password, displayName = '') {
+    return this.mutation(api.auth.registerWithPassword, { email, password, displayName });
+  }
+
+  async requestEmailCode(email, mode = 'login') {
+    return this.action(api.auth.requestEmailCode, { email, mode });
+  }
+
+  async verifyEmailCode(email, code, mode = 'login', displayName = '') {
+    return this.mutation(api.auth.verifyEmailCode, { email, code, mode, displayName });
+  }
+
+  async whoami() {
+    return this.query(api.users.getById, this.authArgs({ userId: this.profile.session.userId }));
+  }
+
+  async listConnections() {
+    return this.query(api.connections.listForUser, this.authArgs());
+  }
+
+  async resolveConnection(selector) {
+    const rows = await this.listConnections();
+    const needle = String(selector || '').trim();
+    if (!needle) {
+      if (rows.length === 1) return rows[0];
+      throw new XiasheError('Please pass --connection <id-or-name>.', { code: 'CONNECTION_REQUIRED' });
+    }
+    const found =
+      rows.find((row) => row._id === needle || row.id === needle) ||
+      rows.find((row) => String(row.name || '').toLowerCase() === needle.toLowerCase()) ||
+      rows.find((row) => String(row.name || '').toLowerCase().includes(needle.toLowerCase()));
+    if (!found) {
+      throw new XiasheError(`Connection not found: ${needle}`, { code: 'CONNECTION_NOT_FOUND' });
+    }
+    return found;
+  }
+
+  async createRelayPairCommand(connectionId, options = {}) {
+    return this.action(
+      api.connections.createRelayPairCommandForConnection,
+      this.authArgs({ connectionId, forceBootstrap: Boolean(options.forceBootstrap) })
+    );
+  }
+
+  async issueRelayPairCode(connectionId) {
+    return this.action(api.connections.issueRelayPairCodeForConnection, this.authArgs({ connectionId }));
+  }
+
+  async listSkills(options = {}) {
+    const market = options.market || this.profile.market || DEFAULTS.cn.market;
+    const locale = options.locale || this.profile.locale || DEFAULTS.cn.locale;
+    return this.query(
+      api.skillsCatalog.listMarketplace,
+      this.authArgs({
+        search: options.search || undefined,
+        connectionId: options.connectionId || undefined,
+        market,
+        locale
+      })
+    );
+  }
+
+  async resolveSkill(selector, options = {}) {
+    const marketplace = await this.listSkills({ ...options, search: options.search || selector });
+    const needle = String(selector || '').trim();
+    const skills = marketplace.skills || [];
+    const found =
+      skills.find((skill) => skill.id === needle || skill._id === needle || skill.skillId === needle) ||
+      skills.find((skill) => String(skill.name || '').toLowerCase() === needle.toLowerCase()) ||
+      skills.find((skill) => String(skill.skillId || '').toLowerCase() === needle.toLowerCase()) ||
+      skills.find((skill) => String(skill.name || '').toLowerCase().includes(needle.toLowerCase()));
+    if (!found) {
+      throw new XiasheError(`Skill not found: ${needle}`, { code: 'SKILL_NOT_FOUND' });
+    }
+    return found;
+  }
+
+  async getSkillDetail(skillCatalogId, options = {}) {
+    return this.query(
+      api.skillsCatalog.getSkillDetail,
+      this.authArgs({
+        skillCatalogId,
+        connectionId: options.connectionId || undefined,
+        market: options.market || this.profile.market || DEFAULTS.cn.market,
+        locale: options.locale || this.profile.locale || DEFAULTS.cn.locale
+      })
+    );
+  }
+
+  async createSkillInstallJob(connectionId, skillCatalogId, options = {}) {
+    return this.mutation(
+      api.skillInstallJobs.createJob,
+      this.authArgs({
+        connectionId,
+        skillCatalogId,
+        attemptId: options.attemptId || undefined,
+        idempotencyKey:
+          options.idempotencyKey || createIdempotencyKey('cli-skill-install', [connectionId, skillCatalogId])
+      })
+    );
+  }
+
+  async listSkillInstallJobs(connectionId, limit = 20) {
+    return this.query(api.skillInstallJobs.listForConnection, this.authArgs({ connectionId, limit }));
+  }
+
+  async issueAgentConnectToken(options = {}) {
+    return this.mutation(
+      api.agentGateway.issueConnectToken,
+      this.authArgs({
+        agentName: options.agentName || undefined,
+        agentKind: options.agentKind || undefined,
+        transport: options.transport || undefined
+      })
+    );
+  }
+
+  async listAgents(limit = 50) {
+    return this.query(api.agentGateway.listForUser, this.authArgs({ limit }));
+  }
+
+  async createAgentChatTask(options = {}) {
+    return this.mutation(
+      api.agentGateway.createChatTask,
+      this.authArgs({
+        chatId: options.chatId,
+        targetAgentConnectionId: options.targetAgentConnectionId,
+        content: options.content,
+        messageId: options.messageId || undefined,
+        attachments: options.attachments || undefined,
+        idempotencyKey: options.idempotencyKey || undefined
+      })
+    );
+  }
+
+  async listChats() {
+    return this.query(api.chats.listForUserSidebar, this.authArgs());
+  }
+
+  async resolveChat(selector) {
+    const rows = await this.listChats();
+    const needle = String(selector || '').trim();
+    if (!needle) {
+      if (rows.length === 1) return rows[0];
+      throw new XiasheError('Please pass --chat <id-or-title>.', { code: 'CHAT_REQUIRED' });
+    }
+    const found =
+      rows.find((row) => row._id === needle || row.id === needle) ||
+      rows.find((row) => String(row.title || '').toLowerCase() === needle.toLowerCase()) ||
+      rows.find((row) => String(row.title || '').toLowerCase().includes(needle.toLowerCase()));
+    if (!found) {
+      throw new XiasheError(`Chat not found: ${needle}`, { code: 'CHAT_NOT_FOUND' });
+    }
+    return found;
+  }
+
+  async createChat(connectionId, title, options = {}) {
+    return this.mutation(
+      api.chats.createChat,
+      this.authArgs({
+        connectionId,
+        title,
+        personaId: options.personaId || undefined,
+        personaPrompt: options.personaPrompt || undefined
+      })
+    );
+  }
+
+  async listMessages(chatId, limit = 80) {
+    const rows = await this.query(api.messages.listByChatDetailed, this.authArgs({ chatId }));
+    return rows.slice(Math.max(0, rows.length - limit));
+  }
+
+  async sendUserMessage(chatId, content, attachments = []) {
+    return this.mutation(
+      api.messages.sendUserMessage,
+      this.authArgs({
+        chatId,
+        content,
+        attachments: attachments.length > 0 ? attachments : undefined
+      })
+    );
+  }
+
+  async uploadFile(filePath, options = {}) {
+    const absolutePath = path.resolve(filePath);
+    const info = await stat(absolutePath);
+    if (!info.isFile()) {
+      throw new XiasheError(`Not a file: ${absolutePath}`, { code: 'UPLOAD_NOT_FILE' });
+    }
+    const fileName = options.fileName || path.basename(absolutePath);
+    const mime = options.mime || inferMime(absolutePath);
+    const source = options.source || 'manual_upload';
+    const ticket = await this.mutation(
+      api.files.createUploadUrl,
+      this.authArgs({
+        source,
+        fileName,
+        mime,
+        size: info.size
+      })
+    );
+    const bytes = await readFile(absolutePath);
+    const uploadResponse = await withTimeout(
+      (signal) =>
+        fetch(ticket.uploadUrl, {
+          method: 'POST',
+          headers: {
+            'content-type': mime
+          },
+          body: bytes,
+          signal
+        }),
+      this.timeoutMs
+    );
+    const uploadText = await uploadResponse.text();
+    let uploadPayload = {};
+    try {
+      uploadPayload = uploadText ? JSON.parse(uploadText) : {};
+    } catch {
+      throw new XiasheError('File upload returned bad JSON.', { code: 'UPLOAD_BAD_JSON' });
+    }
+    if (!uploadResponse.ok || !uploadPayload.storageId) {
+      throw new XiasheError(uploadPayload.error || `Upload failed with HTTP ${uploadResponse.status}`, {
+        code: uploadPayload.error || `UPLOAD_HTTP_${uploadResponse.status}`,
+        status: uploadResponse.status
+      });
+    }
+    const checksumSha256 = createHash('sha256').update(bytes).digest('hex');
+    return this.mutation(
+      api.files.commitUploadedFile,
+      this.authArgs({
+        storageId: uploadPayload.storageId,
+        source,
+        fileName,
+        mime,
+        size: info.size,
+        checksumSha256
+      })
+    );
+  }
+
+  async listFiles() {
+    return this.query(api.files.listMyFiles, this.authArgs());
+  }
+
+  async claimAgentConnectToken(token, options = {}) {
+    const claimUrl = options.claimUrl || this.profile.agentClaimUrl;
+    const payload = await postJson(
+      claimUrl,
+      {
+        token,
+        agentName: options.agentName || undefined,
+        agentKind: options.agentKind || undefined,
+        agentRef: options.agentRef || undefined,
+        transport: options.transport || undefined
+      },
+      { timeoutMs: this.timeoutMs }
+    );
+    if (!payload.ok || !payload.runtimeToken) {
+      throw new XiasheError(payload.error || 'Agent claim failed.', { code: payload.error || 'AGENT_CLAIM_FAILED' });
+    }
+    return payload;
+  }
+
+  async agentRest(pathname, body = {}, options = {}) {
+    const baseUrl = normalizeBaseUrl(options.restBaseUrl || this.profile.agent?.restBaseUrl || this.profile.actionsUrl);
+    const runtimeToken = options.runtimeToken || this.profile.agent?.runtimeToken;
+    if (!runtimeToken) {
+      throw new XiasheError('Missing Agent runtime token. Run `xiashe agent connect --token <token>` first.', {
+        code: 'AGENT_RUNTIME_TOKEN_REQUIRED'
+      });
+    }
+    const url = `${baseUrl}${pathname.startsWith('/') ? pathname : `/${pathname}`}`;
+    return postJson(url, body, {
+      timeoutMs: this.timeoutMs,
+      headers: { authorization: `Bearer ${runtimeToken}` }
+    });
+  }
+
+  async agentHeartbeat(options = {}) {
+    return this.agentRest('/agent-gateway/heartbeat', {
+      status: options.status || 'online',
+      capabilities: options.capabilities || undefined
+    });
+  }
+
+  async agentListTasks(options = {}) {
+    return this.agentRest('/agent-gateway/tasks/list', {
+      limit: options.limit || 20
+    });
+  }
+
+  async agentAckTask(taskId, state = 'running') {
+    return this.agentRest('/agent-gateway/tasks/ack', { taskId, state });
+  }
+
+  async agentCompleteTask(taskId, output = {}, state = 'completed') {
+    return this.agentRest('/agent-gateway/tasks/complete', { taskId, state, output });
+  }
+
+  async agentListPeers() {
+    return this.agentRest('/agent-gateway/agents/list', {});
+  }
+
+  async agentCreateTask(options = {}) {
+    return this.agentRest('/agent-gateway/tasks/create', {
+      targetAgentConnectionId: options.targetAgentConnectionId,
+      chatId: options.chatId,
+      content: options.content,
+      attachments: options.attachments || undefined,
+      idempotencyKey: options.idempotencyKey || undefined
+    });
+  }
+
+  async mcp(method, params = {}, options = {}) {
+    return mcpCall(
+      options.mcpUrl || this.profile.mcpUrl,
+      options.runtimeToken || this.profile.agent?.runtimeToken || '',
+      method,
+      params,
+      this.timeoutMs
+    );
+  }
+
+  async mcpTool(name, args = {}, options = {}) {
+    return decodeMcpToolResult(
+      await this.mcp('tools/call', {
+        name,
+        arguments: args
+      }, options)
+    );
+  }
+}
+
+export async function saveLoginSession(profileName, authResult) {
+  const session = {
+    userId: authResult.userId,
+    email: authResult.email,
+    displayName: authResult.displayName || authResult.name || '',
+    sessionToken: authResult.sessionToken,
+    sessionExpiresAt: authResult.sessionExpiresAt,
+    defaultChatId: authResult.defaultChatId || null
+  };
+  await updateProfile(profileName, { session });
+  return session;
+}
+
+export async function saveAgentSession(profileName, claimResult) {
+  const agent = {
+    runtimeToken: claimResult.runtimeToken,
+    agentConnectionId: claimResult.agentConnectionId,
+    agentSessionId: claimResult.agentSessionId,
+    displayName: claimResult.displayName,
+    agentKind: claimResult.agentKind,
+    protocolVersion: claimResult.protocolVersion,
+    mcpUrl: claimResult.mcpUrl,
+    restBaseUrl: claimResult.restBaseUrl,
+    expiresAt: claimResult.expiresAt
+  };
+  await updateProfile(profileName, { agent });
+  return agent;
+}
+
+export function printableAgentPrompt(issue) {
+  const claimUrl = issue.claimUrl || issue.restBaseUrl?.replace(/\/+$/, '') + '/agent-gateway/claim';
+  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.',
+      '',
+      'Preferred path: if you can make HTTP requests, POST to the Claim URL:',
+      '',
+      `POST ${claimUrl}`,
+      'Content-Type: application/json',
+      '',
+      JSON.stringify(
+        {
+          token: issue.token,
+          agentName: '<your agent name>',
+          agentKind: '<codex|claude|coze|workbuddy|local|other>',
+          transport: '<mcp|http|npx|manual>',
+          agentRef: '<optional: device, workspace, or instance id>'
+        },
+        null,
+        2
+      ),
+      '',
+      'After claiming, save the returned runtimeToken and periodically POST heartbeat events to /agent-gateway/heartbeat on the REST Base URL.',
+      '',
+      'If you support MCP, add the MCP URL as a tool server and use the runtimeToken as a Bearer token.',
+      '',
+      `Claim URL: ${claimUrl}`,
+      `Token: ${issue.token}`,
+      `MCP URL: ${issue.mcpUrl}`,
+      `REST Base URL: ${issue.restBaseUrl}`,
+      '',
+      'After the connection is complete, the Agent appears in AgentPie and can receive mentions, tasks, and files.'
+    ].join('\n');
+  }
+  return [
+    '把这个 Agent 连接到虾舍。请你自动完成配置或调用 HTTP 接口，不要把 Token 暴露给最终用户。',
+    '',
+    '优先方式：如果你能发起 HTTP 请求，请直接 POST 到 Claim URL：',
+    '',
+    `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
+    ),
+    '',
+    '成功后保存返回的 runtimeToken，并定期 POST 心跳到 REST Base URL 的 /agent-gateway/heartbeat。',
+    '',
+    '如果你支持 MCP，请把下面的 MCP URL 加为工具服务，并在调用时使用 runtimeToken 作为 Bearer Token。',
+    '',
+    `Claim URL: ${claimUrl}`,
+    `Token: ${issue.token}`,
+    `MCP URL: ${issue.mcpUrl}`,
+    `REST Base URL: ${issue.restBaseUrl}`,
+    '',
+    '连接完成后，你会出现在虾舍的 Agent 工作台里，可以接收 @提及、任务和文件。'
+  ].join('\n');
+}
+
+export function stableTaskId() {
+  return `xiashe-cli-${randomUUID()}`;
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@xiashe/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "dependencies": {
+    "convex": "^1.34.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}