@realtimex/sdk 1.4.0 → 1.4.3

package/skills/realtimex-moderator-sdk/scripts/rtx.js

@@ -0,0 +1,492 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * rtx.js — RealTimeX SDK CLI (source-verified)
+ * AUTO-GENERATED by scripts/generate-skill.mjs — do not edit by hand.
+ *
+ * All method signatures derived from the @realtimex/sdk TypeScript source.
+ *
+ * Usage: node rtx.js <command> [args...] [--flags]
+ * Global flags:
+ *   --api-key=<key>    Override API key
+ *   --env-dir=<path>   Directory containing .env (default: cwd)
+ *   --url=<url>        RealTimeX server URL (default: http://localhost:3001)
+ */
+
+const path = require('path');
+const { initSDK } = require('./lib/sdk-init');
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const flags = {}, positional = [];
+  for (const arg of argv) {
+    if (arg.startsWith('--')) {
+      const [k, ...rest] = arg.slice(2).split('=');
+      flags[k] = rest.length ? rest.join('=') : true;
+    } else { positional.push(arg); }
+  }
+  return { flags, positional };
+}
+const { flags, positional } = parseArgs(process.argv.slice(2));
+const [command, ...cmdArgs] = positional;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function print(obj) { console.log(JSON.stringify(obj, null, 2)); }
+function printTable(rows, cols) {
+  if (!rows?.length) { console.log('(no results)'); return; }
+  const keys = cols || Object.keys(rows[0]);
+  const widths = keys.map(k => Math.max(k.length, ...rows.map(r => String(r[k] ?? '').length)));
+  const pad = (s, w) => String(s ?? '').padEnd(w);
+  console.log(keys.map((k, i) => pad(k, widths[i])).join('  '));
+  console.log(widths.map(w => '-'.repeat(w)).join('  '));
+  for (const r of rows) console.log(keys.map((k, i) => pad(r[k], widths[i])).join('  '));
+}
+
+let _sdk = null;
+async function getSDK() {
+  if (_sdk) return _sdk;
+  _sdk = await initSDK({ envDir: flags['env-dir'] || process.cwd(), apiKey: flags['api-key'], url: flags['url'] });
+  return _sdk;
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+const CMD = {};
+
+// -- ping -------------------------------------------------------------------
+// Source: index.ts → sdk.ping() → { success, mode, appId, timestamp }
+CMD.ping = async () => { const { sdk } = await getSDK(); print(await sdk.ping()); };
+
+// -- info -------------------------------------------------------------------
+CMD.info = async () => {
+  const { sdk, apiKey } = await getSDK();
+  console.log('API key: ' + apiKey.slice(0, 8) + '...');
+  try { console.log('Data dir: ' + await sdk.getAppDataDir()); } catch (_) {}
+  print(await sdk.ping());
+};
+
+// -- agents -----------------------------------------------------------------
+// Source: modules/api.ts → ApiModule.getAgents() → Agent[]
+// Agent: { slug, name, description?, hub_id? }
+// NOTE: on sdk.api, NOT sdk directly
+CMD.agents = async () => {
+  const { sdk } = await getSDK();
+  printTable(await sdk.api.getAgents(), ['slug', 'name', 'description']);
+};
+
+// -- workspaces -------------------------------------------------------------
+// Source: ApiModule.getWorkspaces() → Workspace[] { id, slug, name, type }
+CMD.workspaces = async () => {
+  const { sdk } = await getSDK();
+  printTable(await sdk.api.getWorkspaces(), ['id', 'slug', 'name', 'type']);
+};
+
+// -- threads ----------------------------------------------------------------
+// Source: ApiModule.getThreads(workspaceSlug) → Thread[] { id, slug, name }
+CMD.threads = async () => {
+  const [slug] = cmdArgs;
+  if (!slug) { console.error('Usage: rtx.js threads <workspace-slug>'); process.exit(1); }
+  const { sdk } = await getSDK();
+  printTable(await sdk.api.getThreads(slug), ['id', 'slug', 'name']);
+};
+
+// -- task -------------------------------------------------------------------
+// Source: ApiModule.getTask(taskUuid) → Task { uuid, title, status, ..., runs }
+CMD.task = async () => {
+  const [uuid] = cmdArgs;
+  if (!uuid) { console.error('Usage: rtx.js task <uuid>'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.api.getTask(uuid));
+};
+
+// -- activities -------------------------------------------------------------
+// Source: ActivitiesModule.list(options?) → Activity[]  (direct array, NOT { activities: [...] })
+CMD.activities = async () => {
+  const { sdk } = await getSDK();
+  const opts = {};
+  if (flags.status) opts.status = flags.status;
+  if (flags.limit)  opts.limit  = Number(flags.limit);
+  if (flags.offset) opts.offset = Number(flags.offset);
+  print(await sdk.activities.list(opts));
+};
+
+// -- activity-get -----------------------------------------------------------
+// Source: ActivitiesModule.get(id) → Activity | null
+CMD['activity-get'] = async () => {
+  const [id] = cmdArgs;
+  if (!id) { console.error('Usage: rtx.js activity-get <id>'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.activities.get(id));
+};
+
+// -- activity-create --------------------------------------------------------
+// Source: ActivitiesModule.insert(rawData: Record<string,unknown>) → Activity
+// rawData is your payload; SDK wraps it in { raw_data: rawData } automatically.
+CMD['activity-create'] = async () => {
+  const [jsonStr] = cmdArgs;
+  if (!jsonStr) { console.error('Usage: rtx.js activity-create <json-payload>'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.activities.insert(JSON.parse(jsonStr)));
+};
+
+// -- activity-update --------------------------------------------------------
+// Source: ActivitiesModule.update(id, updates: Partial<Activity>) → Activity
+CMD['activity-update'] = async () => {
+  const [id, jsonStr] = cmdArgs;
+  if (!id || !jsonStr) { console.error('Usage: rtx.js activity-update <id> <json-updates>'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.activities.update(id, JSON.parse(jsonStr)));
+};
+
+// -- activity-delete --------------------------------------------------------
+// Source: ActivitiesModule.delete(id) → void
+CMD['activity-delete'] = async () => {
+  const [id] = cmdArgs;
+  if (!id) { console.error('Usage: rtx.js activity-delete <id>'); process.exit(1); }
+  const { sdk } = await getSDK();
+  await sdk.activities.delete(id);
+  console.log('Deleted.');
+};
+
+// -- task-start / task-complete / task-fail ---------------------------------
+// Source: modules/task.ts
+// CORRECT signatures (positional, NOT { task_uuid } object):
+//   start(taskUuid, machineIdOrOptions?)
+//   complete(taskUuid, result?, machineIdOrOptions?)
+//   fail(taskUuid, error: string, machineIdOrOptions?)
+CMD['task-start'] = async () => {
+  const [uuid] = cmdArgs;
+  if (!uuid) { console.error('Usage: rtx.js task-start <uuid> [--machine=<id>]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.task.start(uuid, flags.machine ? { machineId: flags.machine } : undefined));
+};
+CMD['task-complete'] = async () => {
+  const [uuid, resultStr] = cmdArgs;
+  if (!uuid) { console.error('Usage: rtx.js task-complete <uuid> [<result-json>] [--machine=<id>]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.task.complete(uuid, resultStr ? JSON.parse(resultStr) : {}, flags.machine ? { machineId: flags.machine } : undefined));
+};
+CMD['task-fail'] = async () => {
+  const [uuid, ...errParts] = cmdArgs;
+  const errMsg = errParts.join(' ');
+  if (!uuid || !errMsg) { console.error('Usage: rtx.js task-fail <uuid> <error-message>'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.task.fail(uuid, errMsg, flags.machine ? { machineId: flags.machine } : undefined));
+};
+CMD['task-progress'] = async () => {
+  const [uuid, dataStr] = cmdArgs;
+  if (!uuid) { console.error('Usage: rtx.js task-progress <uuid> [<progress-json>]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.task.progress(uuid, dataStr ? JSON.parse(dataStr) : {}));
+};
+CMD['task-cancel'] = async () => {
+  const [uuid, ...reasonParts] = cmdArgs;
+  if (!uuid) { console.error('Usage: rtx.js task-cancel <uuid> [<reason>]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.task.cancel(uuid, reasonParts.join(' ') || undefined));
+};
+
+// -- trigger-agent ----------------------------------------------------------
+// IMPORTANT: sdk.webhook.triggerAgent() sends event "task.trigger" which the
+// server rejects (expects "trigger-agent"). This command bypasses the SDK
+// method and uses a direct fetch call with the correct event string.
+// Source evidence: modules/webhook.ts hardcodes event: 'task.trigger'
+//                  server/endpoints/sdk/webhook.js enum: ['trigger-agent',...]
+CMD['trigger-agent'] = async () => {
+  const [agentName, workspaceSlug, ...promptParts] = cmdArgs;
+  const prompt = promptParts.join(' ');
+  if (!agentName || !workspaceSlug || !prompt) {
+    console.error('Usage: rtx.js trigger-agent <agent-name> <workspace-slug> <prompt> [--thread=<slug>] [--data=<json>]');
+    process.exit(1);
+  }
+  const { apiKey } = await getSDK();
+  const resp = await fetch('http://localhost:3001/webhooks/realtimex', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + apiKey },
+    body: JSON.stringify({
+      event: 'trigger-agent',
+      payload: {
+        auto_run: true,
+        agent_name: agentName,
+        workspace_slug: workspaceSlug,
+        thread_slug: flags.thread || undefined,
+        prompt,
+        raw_data: flags.data ? JSON.parse(flags.data) : {},
+      },
+    }),
+  });
+  print(await resp.json());
+};
+
+// -- webhook-ping -----------------------------------------------------------
+// Source: WebhookModule.ping() → sends event: 'system.ping' (accepted by server)
+CMD['webhook-ping'] = async () => {
+  const { sdk } = await getSDK();
+  print(await sdk.webhook.ping());
+};
+
+// -- llm-providers ----------------------------------------------------------
+// Source: LLMModule.chatProviders() → { success, providers: [{ provider, models }] }
+CMD['llm-providers'] = async () => {
+  const { sdk } = await getSDK();
+  const { providers } = await sdk.llm.chatProviders();
+  for (const p of (providers || [])) {
+    console.log('\nProvider: ' + p.provider);
+    if (p.models?.length) printTable(p.models, ['id', 'name']);
+  }
+};
+CMD['embed-providers'] = async () => {
+  const { sdk } = await getSDK();
+  const { providers } = await sdk.llm.embedProviders();
+  for (const p of (providers || [])) {
+    console.log('\nProvider: ' + p.provider);
+    if (p.models?.length) printTable(p.models, ['id', 'name']);
+  }
+};
+
+// -- llm-chat ---------------------------------------------------------------
+// Source: LLMModule.chat() → ChatResponse { success, response?: { content, model, metrics } }
+// Access text via res.response?.content  (NOT choices[0].message.content)
+// Stream: yields StreamChunk { textResponse?, close?, error? }  (NOT delta.content)
+CMD['llm-chat'] = async () => {
+  const message = cmdArgs.join(' ');
+  if (!message) { console.error('Usage: rtx.js llm-chat <message> [--stream] [--model=<m>] [--provider=<p>]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  const opts = {};
+  if (flags.model)    opts.model    = flags.model;
+  if (flags.provider) opts.provider = flags.provider;
+  if (flags.stream) {
+    for await (const chunk of sdk.llm.chatStream([{ role: 'user', content: message }], opts)) {
+      if (chunk.textResponse) process.stdout.write(chunk.textResponse);
+      if (chunk.close) break;
+    }
+    process.stdout.write('\n');
+  } else {
+    const res = await sdk.llm.chat([{ role: 'user', content: message }], opts);
+    console.log(res.response?.content ?? res.error ?? JSON.stringify(res));
+  }
+};
+
+// -- llm-embed --------------------------------------------------------------
+// Source: LLMModule.embed(input: string | string[], options?)
+// Returns: EmbedResponse { success, embeddings: number[][], model, dimensions }
+CMD['llm-embed'] = async () => {
+  const text = cmdArgs.join(' ');
+  if (!text) { console.error('Usage: rtx.js llm-embed <text> [--model=<m>]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  const res = await sdk.llm.embed(text, { model: flags.model, provider: flags.provider });
+  console.log('success: ' + res.success + ', model: ' + res.model + ', dimensions: ' + res.dimensions);
+  if (flags.vectors && res.embeddings?.[0]) print(res.embeddings[0].slice(0, 10));
+};
+
+// -- mcp-servers ------------------------------------------------------------
+// Source: MCPModule.getServers(provider?: 'local'|'remote'|'all')
+// CORRECT: plain string arg, NOT { provider: 'all' }
+CMD['mcp-servers'] = async () => {
+  const { sdk } = await getSDK();
+  printTable(await sdk.mcp.getServers(flags.provider || 'all'), ['name', 'provider', 'status']);
+};
+CMD['mcp-tools'] = async () => {
+  const [name] = cmdArgs;
+  if (!name) { console.error('Usage: rtx.js mcp-tools <server-name> [--provider=local|remote]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  printTable(await sdk.mcp.getTools(name, flags.provider), ['name', 'description']);
+};
+CMD['mcp-exec'] = async () => {
+  const [server, tool, argsStr] = cmdArgs;
+  if (!server || !tool) { console.error('Usage: rtx.js mcp-exec <server> <tool> [<args-json>] [--provider=local|remote]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.mcp.executeTool(server, tool, argsStr ? JSON.parse(argsStr) : {}, flags.provider));
+};
+
+// -- acp-agents -------------------------------------------------------------
+// Source: AcpAgentModule.listAgents({ includeModels? })
+// Returns: AcpAgentInfo[] { id, label, handles[], installed, authReady, status }
+CMD['acp-agents'] = async () => {
+  const { sdk } = await getSDK();
+  printTable(await sdk.acpAgent.listAgents({ includeModels: flags.models === 'true' }), ['id', 'label', 'status', 'authReady', 'installed']);
+};
+CMD['acp-sessions'] = async () => {
+  const { sdk } = await getSDK();
+  print(await sdk.acpAgent.listSessions());
+};
+
+// -- acp-chat ---------------------------------------------------------------
+// Source: AcpAgentModule.createSession + streamChat
+// approvalPolicy: 'approve-all' | 'approve-reads' | 'deny-all'
+// StreamEvent types: text_delta | status | tool_call | permission_request | done | error | close
+// text_delta.data.type === 'thinking' → internal reasoning (not final output)
+CMD['acp-chat'] = async () => {
+  const [agentId, ...msgParts] = cmdArgs;
+  const message = msgParts.join(' ');
+  if (!agentId || !message) {
+    console.error('Usage: rtx.js acp-chat <agent-id> <message> [--cwd=<path>] [--model=<m>] [--policy=approve-all]');
+    process.exit(1);
+  }
+  const { sdk } = await getSDK();
+  const sessionOpts = { agent_id: agentId, cwd: flags.cwd || process.cwd(), approvalPolicy: flags.policy || 'approve-all' };
+  if (flags.model) sessionOpts.model = flags.model;
+  process.stderr.write('Creating ACP session for "' + agentId + '"...\n');
+  const session = await sdk.acpAgent.createSession(sessionOpts);
+  try {
+    for await (const event of sdk.acpAgent.streamChat(session.session_key, message)) {
+      if (event.type === 'text_delta') {
+        if (event.data.type === 'thinking') { if (flags.thoughts) process.stderr.write('[thought] ' + event.data.text + '\n'); }
+        else process.stdout.write(String(event.data.text ?? ''));
+      } else if (event.type === 'tool_call') {
+        if (!flags.quiet) process.stderr.write('\n[tool: ' + event.data.tool + ']\n');
+      } else if (event.type === 'error') {
+        process.stderr.write('\nError: ' + event.data.message + '\n');
+      } else if (event.type === 'done' || event.type === 'close') {
+        process.stdout.write('\n');
+      }
+    }
+  } finally { await sdk.acpAgent.closeSession(session.session_key).catch(() => {}); }
+};
+
+// -- tts-providers / stt-providers ------------------------------------------
+CMD['tts-providers'] = async () => { const { sdk } = await getSDK(); printTable(await sdk.tts.listProviders(), ['id', 'name', 'type', 'configured', 'supportsStreaming']); };
+CMD['stt-providers'] = async () => { const { sdk } = await getSDK(); print(await sdk.stt.listProviders()); };
+
+// -- vectors ----------------------------------------------------------------
+// Source: LLMModule.vectors (VectorStore sub-module)
+CMD['vectors-workspaces'] = async () => { const { sdk } = await getSDK(); print(await sdk.llm.vectors.listWorkspaces()); };
+// llm.search() embeds query then calls vectors.query() — high-level helper
+CMD['vectors-query'] = async () => {
+  const query = cmdArgs.join(' ');
+  if (!query) { console.error('Usage: rtx.js vectors-query <query> [--workspace-id=<id>] [--top=5]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.llm.search(query, { topK: flags.top ? Number(flags.top) : 5, workspaceId: flags['workspace-id'] }));
+};
+// vectors.upsert: VectorRecord[] = { id, vector: number[], metadata? }
+CMD['vectors-upsert'] = async () => {
+  const [jsonStr] = cmdArgs;
+  if (!jsonStr) { console.error('Usage: rtx.js vectors-upsert <json-VectorRecord[]> [--workspace-id=<id>]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.llm.vectors.upsert(JSON.parse(jsonStr), { workspaceId: flags['workspace-id'] }));
+};
+// vectors.delete requires { deleteAll: true } — partial delete by ID not supported
+CMD['vectors-delete'] = async () => {
+  if (!flags['workspace-id'] && !flags.all) { console.error('Usage: rtx.js vectors-delete --workspace-id=<id>  OR  --all'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.llm.vectors.delete({ deleteAll: true, workspaceId: flags['workspace-id'] }));
+};
+
+// -- contract ---------------------------------------------------------------
+CMD['contract-info']         = async () => { const { sdk } = await getSDK(); print(await sdk.contract.getLocalAppV1()); };
+CMD['contract-capabilities'] = async () => { const { sdk } = await getSDK(); print(await sdk.contract.listCapabilities()); };
+CMD['contract-search']       = async () => {
+  const query = cmdArgs.join(' ');
+  if (!query) { console.error('Usage: rtx.js contract-search <query>'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.contract.searchCapabilities(query));
+};
+CMD['contract-invoke'] = async () => {
+  const [capId, ...rest] = cmdArgs;
+  if (!capId) { console.error('Usage: rtx.js contract-invoke <capability-id> [<args-json>]'); process.exit(1); }
+  const { sdk } = await getSDK();
+  print(await sdk.contract.invoke({ capability_id: capId, args: rest[0] ? JSON.parse(rest[0]) : {}, auto_run: true, agent_name: flags.agent, workspace_slug: flags.workspace, prompt: flags.prompt }));
+};
+
+// -- database / auth --------------------------------------------------------
+CMD['db-config']   = async () => { const { sdk } = await getSDK(); print(await sdk.database.getConfig()); };
+CMD['auth-token']  = async () => { const { sdk } = await getSDK(); print(await sdk.auth.getAccessToken()); };
+
+// -- help -------------------------------------------------------------------
+CMD.help = async () => {
+  console.log(`
+RealTimeX SDK CLI (source-verified) — rtx.js
+============================================
+
+Usage: node rtx.js <command> [args...] [--flags]
+
+Global flags:
+  --api-key=<key>       Override API key (skips .env lookup)
+  --env-dir=<path>      Directory containing .env (default: cwd)
+  --url=<url>           RealTimeX server URL (default: http://localhost:3001)
+
+Connection:
+  ping / info
+
+sdk.api.*:
+  agents / workspaces / threads <slug> / task <uuid>
+
+sdk.activities.*:
+  activities [--status --limit --offset]
+  activity-get <id>
+  activity-create <json>
+  activity-update <id> <json>
+  activity-delete <id>
+
+sdk.task.*  (positional args — NOT { task_uuid }):
+  task-start <uuid> [--machine=<id>]
+  task-complete <uuid> [<result-json>] [--machine=<id>]
+  task-fail <uuid> <error-message>
+  task-progress <uuid> [<progress-json>]
+  task-cancel <uuid> [<reason>]
+
+Trigger  (raw fetch — SDK method sends wrong event type):
+  trigger-agent <agent-name> <workspace-slug> <prompt>
+    [--thread=<slug>] [--data=<json>]
+
+Webhook:
+  webhook-ping
+
+sdk.llm.*:
+  llm-providers / embed-providers
+  llm-chat <message> [--stream] [--model] [--provider]
+  llm-embed <text> [--model] [--vectors]
+
+sdk.llm.vectors.*:
+  vectors-workspaces
+  vectors-query <text> [--workspace-id] [--top=5]
+  vectors-upsert <json-VectorRecord[]> [--workspace-id]
+  vectors-delete --workspace-id=<id> | --all
+
+sdk.mcp.*:
+  mcp-servers [--provider=local|remote|all]
+  mcp-tools <server> [--provider]
+  mcp-exec <server> <tool> [<args-json>] [--provider]
+
+sdk.acpAgent.*:
+  acp-agents [--models=true]
+  acp-sessions
+  acp-chat <agent-id> <message>
+    [--cwd] [--model] [--policy=approve-all] [--thoughts] [--quiet]
+
+sdk.tts.* / sdk.stt.*:
+  tts-providers / stt-providers
+
+sdk.contract.*:
+  contract-info / contract-capabilities
+  contract-search <query>
+  contract-invoke <capability-id> [<args-json>] [--agent] [--workspace] [--prompt]
+
+sdk.database.* / sdk.auth.*:
+  db-config / auth-token
+
+  help
+`);
+};
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+(async () => {
+  const handler = CMD[command];
+  if (!handler) {
+    console.error('Unknown command: ' + (command || '(none)') + '\nRun: node rtx.js help');
+    process.exit(1);
+  }
+  try { await handler(); }
+  catch (err) {
+    console.error('Error:', err.message || err);
+    if (flags.debug) console.error(err);
+    process.exit(1);
+  }
+})();