@xmemo/skill 1.1.25

package/skill/scripts/commands/ops.mjs

@@ -0,0 +1,236 @@
+import {
+  SCRIPT_COMMAND,
+  EXIT_CODE,
+  exitCodeForHttpStatus,
+  exitCodeForErrorCode,
+  exitCodeForError,
+} from '../lib/core.mjs';
+
+import {
+  makeHttpRequest,
+  parseJsonResponse,
+  extractRequestId,
+  extractId,
+  extractList,
+  apiErrorMessage,
+  safeJson,
+  sanitizeTerminalText,
+  formatMemoryContent,
+} from '../lib/api.mjs';
+
+function discoveryString(value) {
+  if (typeof value !== 'string') return null;
+  const sanitized = sanitizeTerminalText(value).trim();
+  return sanitized ? sanitized.slice(0, 200) : null;
+}
+
+function discoveryStringList(value, maxItems = 24) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((item) => typeof item === 'string')
+    .map(discoveryString)
+    .filter(Boolean)
+    .slice(0, maxItems);
+}
+
+function summarizeDoctorDiscovery(discovery, discoveryUrl) {
+  const standalone = discovery?.standalone_skill ?? discovery?.integrations?.standalone_skill ?? {};
+  return {
+    status: 'available',
+    url: discoveryUrl,
+    schemaVersion: discoveryString(discovery?.schema_version),
+    protocol: discoveryString(discovery?.protocol),
+    service: discoveryString(discovery?.service),
+    serviceVersion: discoveryString(discovery?.service_version),
+    mcpUrl: discoveryString(discovery?.mcp_url),
+    supportedClients: discoveryStringList(discovery?.supported_clients),
+    standaloneSkill: {
+      status: discoveryString(standalone.status),
+      runtimeModel: discoveryString(standalone.runtime_model),
+      packageVersion: discoveryString(standalone.package?.version),
+      operations: discoveryStringList(standalone.operations),
+      defaultScopes: discoveryStringList(standalone.auth?.default_scopes),
+    },
+  };
+}
+
+function discoveryFailureCode(error) {
+  const message = String(error?.message ?? '').toLowerCase();
+  if (message.includes('timed out')) return 'timeout';
+  if (message.includes('non-json')) return 'invalid_response';
+  return 'request_failed';
+}
+
+async function fetchDoctorDiscovery(baseUrl, timeoutMs) {
+  const discoveryUrl = new URL('/.well-known/agent-discovery.json', baseUrl).toString();
+  try {
+    const res = await makeHttpRequest(baseUrl, '/.well-known/agent-discovery.json', 'GET', null, {}, timeoutMs);
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      return {
+        status: 'unavailable',
+        url: discoveryUrl,
+        errorCode: 'http_error',
+        httpStatus: res.statusCode ?? null,
+      };
+    }
+    return summarizeDoctorDiscovery(parseJsonResponse(res, 'Doctor discovery'), discoveryUrl);
+  } catch (error) {
+    return {
+      status: 'unavailable',
+      url: discoveryUrl,
+      errorCode: discoveryFailureCode(error),
+    };
+  }
+}
+
+function doctorNextAction({ credential, anonymous }) {
+  if (!anonymous && !credential) {
+    return {
+      command: `${SCRIPT_COMMAND} login --allow-plaintext`,
+      reason: 'Sign in before using account-scoped memory operations.',
+    };
+  }
+  return {
+    command: `${SCRIPT_COMMAND} auth status --verify`,
+    reason: 'Verify the credential separately when an authenticated follow-up is needed.',
+  };
+}
+
+function withDoctorDiagnostics(data, discovery, nextAction) {
+  const report = data && typeof data === 'object' && !Array.isArray(data)
+    ? { ...data }
+    : { ok: true, result: data };
+  return {
+    ...report,
+    clientDiagnostics: {
+      discovery,
+      nextAction,
+    },
+  };
+}
+
+export async function handleOps(ctx) {
+  const { command, options, flags, credential, token } = ctx;
+
+  // Doctor can be anonymous
+  if (command === 'doctor' && !token) {
+    try {
+      const discovery = options.json
+        ? await fetchDoctorDiscovery(options.baseUrl, options.timeoutMs)
+        : null;
+      const res = await makeHttpRequest(options.baseUrl, '/v1/skill/operations', 'POST', {
+        operation: 'doctor',
+        arguments: {}
+      }, {}, options.timeoutMs);
+      const data = parseJsonResponse(res, 'Doctor health check');
+      if (res.statusCode < 200 || res.statusCode >= 300 || data.ok === false) {
+        const reqId = extractRequestId(data);
+        const reqSuffix = reqId ? ` (request_id: ${reqId})` : '';
+        console.error(`Doctor health check failed: ${apiErrorMessage(data, safeJson(data))}${reqSuffix}`);
+        process.exit(exitCodeForErrorCode(data?.error?.code) ?? exitCodeForHttpStatus(res.statusCode));
+      }
+      if (options.json) {
+        console.log(safeJson(withDoctorDiagnostics(data, discovery, doctorNextAction({
+          credential,
+          anonymous: options.anonymous,
+        }))));
+      } else {
+        const authentication = options.anonymous
+          ? 'Not checked (anonymous mode)'
+          : 'Missing/Unauthenticated';
+        const nextStep = options.anonymous
+          ? ''
+          : `\nNext: ${SCRIPT_COMMAND} login --allow-plaintext`;
+        console.log(`XMemo Service Status: OK\nAuthentication: ${authentication}${nextStep}`);
+      }
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Doctor health check failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+
+  // Normalize commands for operations mapping
+  let opName = command;
+  if (command === 'save-state' || command === 'state-save') opName = 'state-save';
+  if (command === 'restore-state' || command === 'state-restore') opName = 'state-restore';
+
+  try {
+    const discovery = command === 'doctor' && options.json
+      ? await fetchDoctorDiscovery(options.baseUrl, options.timeoutMs)
+      : null;
+    // Dispatches operation query to XMemo API over HTTPS with Bearer authorization.
+    const res = await makeHttpRequest(options.baseUrl, '/v1/skill/operations', 'POST', {
+      operation: opName,
+      arguments: flags,
+    }, {
+      'Authorization': `Bearer ${token}`
+    }, options.timeoutMs);
+
+    const data = parseJsonResponse(res, `${opName} request`);
+    const isDoctorAuthInvalid = opName === 'doctor' && data.result?.auth_valid === false;
+    const succeeded = res.statusCode >= 200 && res.statusCode < 300 && data.ok !== false && !isDoctorAuthInvalid;
+    if (options.json) {
+      const output = opName === 'doctor'
+        ? withDoctorDiagnostics(data, discovery, doctorNextAction({ credential, anonymous: false }))
+        : data;
+      console.log(safeJson(output));
+      const failureExitCode = isDoctorAuthInvalid
+        ? EXIT_CODE.AUTH_ERROR
+        : (exitCodeForErrorCode(data?.error?.code) ?? exitCodeForHttpStatus(res.statusCode));
+      process.exit(succeeded ? EXIT_CODE.SUCCESS : failureExitCode);
+    }
+
+    if (!succeeded) {
+      const reqId = extractRequestId(data);
+      const reqSuffix = reqId ? ` (request_id: ${reqId})` : '';
+      console.error(`Error: ${apiErrorMessage(data)} (Code: ${data.error?.code || `HTTP ${res.statusCode}`})${reqSuffix}`);
+      const failureExitCode = exitCodeForErrorCode(data?.error?.code) ?? exitCodeForHttpStatus(res.statusCode);
+      process.exit(failureExitCode);
+    }
+
+    if (opName === 'doctor') {
+      const isValid = !!data.result?.auth_valid;
+      if (isValid) {
+        console.log(`XMemo Service Status: OK\nAuthentication: Valid\nScopes: ${extractList(data.result?.scopes).join(', ')}`);
+      } else {
+        console.log(`XMemo Service Status: OK\nAuthentication: Invalid`);
+        process.exit(EXIT_CODE.AUTH_ERROR);
+      }
+    } else if (opName === 'todo-list') {
+      const todos = extractList(data.result);
+      if (todos.length === 0) {
+        console.log('No TODOs found.');
+      } else {
+        todos.forEach((todo) => {
+          console.log(`- [${todo?.status === 'done' ? 'x' : ' '}] ${sanitizeTerminalText(todo?.content || '')} (ID: ${sanitizeTerminalText(todo?.id || todo?.memory_id || '(unknown)')})`);
+        });
+      }
+    } else if (opName === 'state-restore') {
+      const state = data.result;
+      if (!state || typeof state !== 'object') {
+        console.log('No saved working state found for the requested key.');
+      } else {
+        const stateKey = state.state_key || flags.key || flags.state_key || '(unknown)';
+        const content = state.content === undefined || state.content === null || state.content === ''
+          ? '(empty)'
+          : state.content;
+        console.log(`Working State restored:\nKey: ${sanitizeTerminalText(stateKey)}\nContent: ${formatMemoryContent(content, false)}`);
+      }
+    } else if (opName === 'expense-add') {
+      console.log(`✅ Expense recorded.\nID: ${sanitizeTerminalText(extractId(data.result))}`);
+    } else if (opName === 'todo-add') {
+      const id = extractId(data.result);
+      console.log(`✅ TODO added.${id ? `\nID: ${sanitizeTerminalText(id)}` : ''}`);
+    } else if (opName === 'todo-done') {
+      const id = flags.id || flags.todo_id || extractId(data.result);
+      console.log(`✅ TODO completed.${id ? `\nID: ${sanitizeTerminalText(id)}` : ''}`);
+    } else {
+      console.log(`✅ Operation succeeded.`);
+    }
+    process.exit(EXIT_CODE.SUCCESS);
+  } catch (e) {
+    console.error('Request failed:', e.message);
+    process.exit(exitCodeForError(e));
+  }
+}

package/skill/scripts/lib/api.mjs

@@ -0,0 +1,311 @@
+import https from 'node:https';
+import http from 'node:http';
+import {
+  DEFAULT_BASE_URL,
+  DEFAULT_TIMEOUT_MS,
+  MAX_RESPONSE_BYTES,
+  DEFAULT_TEMPORARY_LIMITS,
+  EXIT_CODE,
+  exitCodeForHttpStatus,
+  exitCodeForErrorCode,
+  exitCodeForError,
+} from './core.mjs';
+import { configureEgressRequest, sanitizeSensitiveValue } from './openclaw-egress.mjs';
+
+export const warnedCredentialOrigins = new Set();
+
+export function redactSensitiveResponse(value) {
+  if (value === null || typeof value !== 'object') {
+    return sanitizeSensitiveValue(value);
+  }
+  if (Array.isArray(value)) return value.map(redactSensitiveResponse);
+  const sensitiveKeys = new Set([
+    'access_token', 'refresh_token', 'id_token', 'temporary_token', 'formal_token',
+    'confirmation_token', 'pending_confirmation_token', 'device_code', 'token',
+    'authorization', 'api_key', 'apikey', 'cookie', 'set-cookie',
+  ]);
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    sensitiveKeys.has(key.toLowerCase()) ? '[REDACTED]' : redactSensitiveResponse(item),
+  ]));
+}
+
+export function safeJson(value) {
+  return JSON.stringify(redactSensitiveResponse(value));
+}
+
+export function sanitizeTerminalText(value) {
+  return String(value ?? '')
+    .replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '')
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '');
+}
+
+export function formatMemoryContent(content, compact) {
+  const value = sanitizeTerminalText(content);
+  const rendered = compact ? value.replace(/\s+/g, ' ').trim() : value;
+  const limit = compact ? 280 : 2_000;
+  return rendered.length > limit ? `${rendered.slice(0, limit)}… (truncated)` : rendered;
+}
+
+export function formatDuration(seconds) {
+  if (seconds % 86_400 === 0) return `${seconds / 86_400} days`;
+  if (seconds % 3_600 === 0) return `${seconds / 3_600} hours`;
+  return `${seconds} seconds`;
+}
+
+export function parseJsonResponse(res, context) {
+  const body = typeof res.body === 'string' ? res.body.trim() : '';
+  if (!body) {
+    const error = new Error(`${context}: server returned an empty response (HTTP ${res.statusCode}).`);
+    error.statusCode = res.statusCode;
+    throw error;
+  }
+  try {
+    return JSON.parse(body);
+  } catch {
+    const safeBody = sanitizeTerminalText(body);
+    const preview = safeBody.length > 2_000 ? `${safeBody.slice(0, 2_000)}…` : safeBody;
+    const error = new Error(`${context}: server returned a non-JSON response (HTTP ${res.statusCode}): ${preview}`);
+    error.statusCode = res.statusCode;
+    throw error;
+  }
+}
+
+export function extractList(result) {
+  if (Array.isArray(result)) return result;
+  if (Array.isArray(result?.results)) return result.results;
+  if (Array.isArray(result?.todos)) return result.todos;
+  if (Array.isArray(result?.reminders)) return result.reminders;
+  return [];
+}
+
+export function extractId(result) {
+  if (typeof result === 'string') return result;
+  if (result?.id) return result.id;
+  if (result?.memory_id) return result.memory_id;
+  return JSON.stringify(result) ?? String(result ?? '');
+}
+
+export function apiErrorMessage(data, fallback = 'Operation failed') {
+  const candidate = data?.error?.message || data?.error_description || data?.detail || data?.error;
+  if (typeof candidate === 'string') return sanitizeTerminalText(candidate);
+  if (candidate !== undefined && candidate !== null) return safeJson(candidate);
+  return fallback;
+}
+
+export function extractRequestId(data) {
+  if (!data || typeof data !== 'object') return null;
+  const candidate = data.error?.request_id || data.request_id;
+  if (typeof candidate === 'string' && candidate.trim()) {
+    return sanitizeTerminalText(candidate.trim());
+  }
+  return null;
+}
+
+export function extractExpiresInSeconds(data) {
+  if (data?.expires_in !== undefined && data?.expires_in !== null) {
+    const num = Number(data.expires_in);
+    if (Number.isFinite(num) && num > 0) return num;
+  }
+  const raw = data?.expires;
+  const exp = (typeof raw === 'number' || typeof raw === 'string') ? Number(raw) : NaN;
+  if (Number.isFinite(exp) && exp > 0) {
+    if (exp > 1e11) return Math.max(1, Math.round((exp - Date.now()) / 1000));
+    if (exp > 1e8) return Math.max(1, Math.round(exp - Date.now() / 1000));
+    return exp;
+  }
+  if (typeof raw === 'string') {
+    const parsedDate = Date.parse(raw);
+    if (Number.isFinite(parsedDate) && parsedDate > Date.now()) {
+      return Math.max(1, Math.round((parsedDate - Date.now()) / 1000));
+    }
+  }
+  return 600;
+}
+
+export function formatRemainingValidity(seconds) {
+  const totalSeconds = Math.max(0, Math.floor(Number(seconds) || 0));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const secs = totalSeconds % 60;
+  if (hours > 0) {
+    return `${hours}h${minutes}m${secs}s`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m${secs}s`;
+  }
+  return `${secs}s`;
+}
+
+export function outputRestError(code, message, options, dataOrRequestId, explicitExitCode = null) {
+  const reqId = typeof dataOrRequestId === 'string'
+    ? sanitizeTerminalText(dataOrRequestId.trim())
+    : extractRequestId(dataOrRequestId);
+  if (options && options.json) {
+    const errorObj = { code, message };
+    if (reqId) {
+      errorObj.request_id = reqId;
+    }
+    console.log(safeJson({ ok: false, error: errorObj }));
+  } else {
+    const reqSuffix = reqId ? ` (request_id: ${reqId})` : '';
+    console.error(`Error: ${message} (Code: ${code})${reqSuffix}`);
+  }
+  const resolvedExitCode = explicitExitCode !== null
+    ? explicitExitCode
+    : (exitCodeForErrorCode(code) ?? EXIT_CODE.USER_ERROR);
+  process.exit(resolvedExitCode);
+}
+
+export function outputContentTooLarge(message, options) {
+  if (options && options.json) {
+    console.log(safeJson({ ok: false, error: { code: 'content_too_large', message } }));
+  } else {
+    console.error(`Error: ${message}`);
+  }
+  process.exit(EXIT_CODE.USER_ERROR);
+}
+
+export function outputJsonFailure(data, statusCode) {
+  const reqId = extractRequestId(data);
+  let payload;
+  if (data && typeof data === 'object' && data.ok === false && data.error && typeof data.error === 'object') {
+    const errorObj = { ...data.error };
+    if (reqId && !errorObj.request_id) errorObj.request_id = reqId;
+    payload = { ...data, ok: false, error: errorObj };
+  } else {
+    const code = data?.error?.code || (Number(statusCode) === 400 ? 'invalid_request' : `HTTP ${statusCode}`);
+    const errorObj = { code, message: apiErrorMessage(data) };
+    if (reqId) errorObj.request_id = reqId;
+    payload = { ok: false, error: errorObj };
+  }
+  console.log(safeJson(payload));
+  process.exit(exitCodeForErrorCode(data?.error?.code) ?? exitCodeForHttpStatus(statusCode));
+}
+
+export function handleRestError(res, { notFoundMessage, context = 'REST request', options }) {
+  if (res.statusCode === 401 || res.statusCode === 403) {
+    let errData = null;
+    try { errData = parseJsonResponse(res, context); } catch {}
+    const code = errData?.error?.code || (res.statusCode === 401 ? 'unauthorized' : 'forbidden');
+    const defaultMsg = res.statusCode === 401
+      ? 'Authentication required or token invalid.'
+      : 'Access denied. Re-authorization is required to explicitly grant the required scope.';
+    let msg = apiErrorMessage(errData, defaultMsg);
+    if (res.statusCode === 403 && !/re-?authorization/i.test(msg)) {
+      msg = `${msg.replace(/\.*$/, '')}. Re-authorization is required to explicitly grant the required scope.`;
+    }
+    outputRestError(code, msg, options, errData, EXIT_CODE.AUTH_ERROR);
+  }
+
+  if (res.statusCode === 404) {
+    let errData = null;
+    try { errData = parseJsonResponse(res, context); } catch {}
+    const code = 'not_found';
+    const msg = apiErrorMessage(errData, notFoundMessage || 'Resource not found.');
+    outputRestError(code, msg, options, errData, EXIT_CODE.USER_ERROR);
+  }
+
+  const data = parseJsonResponse(res, context);
+  if (res.statusCode < 200 || res.statusCode >= 300 || data.ok === false) {
+    const code = data?.error?.code || (res.statusCode === 400 ? 'invalid_request' : `HTTP ${res.statusCode}`);
+    const msg = apiErrorMessage(data);
+    const exitCode = exitCodeForErrorCode(data?.error?.code) ?? exitCodeForHttpStatus(res.statusCode);
+    outputRestError(code, msg, options, data, exitCode);
+  }
+  return data;
+}
+
+// HTTP request helper
+export function makeHttpRequest(baseUrl, apiPath, method, body = null, headers = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    try {
+      const url = new URL(apiPath, baseUrl);
+      const client = url.protocol === 'https:' ? https : http;
+      const bodyStr = body ? JSON.stringify(body) : null;
+      const reqHeaders = {
+        'Content-Type': 'application/json',
+        ...headers,
+      };
+      if (bodyStr) {
+        reqHeaders['Content-Length'] = Buffer.byteLength(bodyStr);
+      }
+      const options = {
+        method: method.toUpperCase(),
+        headers: reqHeaders,
+      };
+      const authorizationHeader = Object.entries(reqHeaders)
+        .find(([key]) => key.toLowerCase() === 'authorization')?.[1];
+      configureEgressRequest(options, authorizationHeader, url);
+      if (authorizationHeader && url.origin !== new URL(DEFAULT_BASE_URL).origin && !warnedCredentialOrigins.has(url.origin)) {
+        warnedCredentialOrigins.add(url.origin);
+        console.error(`⚠️ Sending an XMemo credential to custom origin ${url.origin}. Continue only if this host is trusted.`);
+      }
+
+      let settled = false;
+      const settleResolve = (value) => {
+        if (settled) return;
+        settled = true;
+        resolve(value);
+      };
+      const settleReject = (error) => {
+        if (settled) return;
+        settled = true;
+        reject(error);
+      };
+      const req = client.request(url, options, (res) => {
+        let data = '';
+        let responseBytes = 0;
+        res.on('data', (chunk) => {
+          responseBytes += Buffer.byteLength(chunk);
+          if (responseBytes > MAX_RESPONSE_BYTES) {
+            const error = new Error(`Server response exceeded the ${MAX_RESPONSE_BYTES}-byte safety limit.`);
+            settleReject(error);
+            res.destroy();
+            return;
+          }
+          data += chunk;
+        });
+        res.on('end', () => {
+          settleResolve({
+            statusCode: res.statusCode,
+            headers: res.headers,
+            body: data,
+          });
+        });
+        res.on('error', settleReject);
+        res.on('aborted', () => settleReject(new Error('Server response was interrupted.')));
+      });
+      req.setTimeout(timeoutMs, () => {
+        req.destroy(new Error(`Request timed out after ${timeoutMs} ms.`));
+      });
+      req.on('error', settleReject);
+      if (bodyStr) {
+        req.write(bodyStr);
+      }
+      req.end();
+    } catch (e) {
+      reject(e);
+    }
+  });
+}
+
+export async function fetchTemporaryLimits(baseUrl, timeoutMs) {
+  try {
+    const res = await makeHttpRequest(baseUrl, '/.well-known/xmemo-agent.json', 'GET', null, {}, timeoutMs);
+    if (res.statusCode < 200 || res.statusCode >= 300) return { ...DEFAULT_TEMPORARY_LIMITS };
+    const data = parseJsonResponse(res, 'Temporary-memory policy discovery');
+    const limits = data?.temporary_token?.limits;
+    const max_items = Number(limits?.max_items);
+    const ttl_seconds = Number(limits?.ttl_seconds);
+    const max_lifetime_seconds = Number(limits?.max_lifetime_seconds);
+    if (![max_items, ttl_seconds, max_lifetime_seconds].every(Number.isSafeInteger)
+      || max_items <= 0 || ttl_seconds <= 0 || max_lifetime_seconds <= 0) {
+      return { ...DEFAULT_TEMPORARY_LIMITS };
+    }
+    return { max_items, ttl_seconds, max_lifetime_seconds };
+  } catch {
+    // Discovery must not make an otherwise available registration endpoint unusable.
+    return { ...DEFAULT_TEMPORARY_LIMITS };
+  }
+}