@realtimex/sdk 1.4.0 → 1.4.3

package/skills/realtimex-moderator-sdk/references/known-issues.md

@@ -0,0 +1,237 @@
+# Known Issues — Source-Detected
+
+> Auto-generated by `scripts/generate-skill.mjs` · SDK **1.4.3** · 2026-03-26
+
+Run `node scripts/generate-skill.mjs --force` after SDK source changes to refresh.
+
+**12/12 issues confirmed in current source.**
+
+---
+
+## 1. `sdk.webhook.triggerAgent()` sends `event: "task.trigger"` — server expects `"trigger-agent"`
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/webhook.ts`  
+**Evidence:** `Found `event: "task.trigger"` hardcoded in triggerAgent() body (line ~100)`
+
+**Correct usage:**
+```js
+// ❌ WRONG — SDK sends 'task.trigger' but server enum only accepts 'trigger-agent'
+await sdk.webhook.triggerAgent({ auto_run: true, agent_name: 'agent', ... });
+
+// ✅ CORRECT — raw fetch with server-expected event string
+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: 'document2speech', workspace_slug: 'sdfsdf', prompt: '...' },
+  }),
+});
+```
+
+---
+
+## 2. `sdk.task.start/complete/fail` take positional `(taskUuid, ...)` — NOT `{ task_uuid }` object
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/task.ts`  
+**Evidence:** `start(taskUuid: string, ...) | complete(taskUuid, result, ...) | fail(taskUuid, error: string, ...)`
+
+**Correct usage:**
+```js
+// ❌ WRONG
+await sdk.task.start({ task_uuid: uuid });
+await sdk.task.complete({ task_uuid: uuid, result: { out: 'done' } });
+
+// ✅ CORRECT
+await sdk.task.start(uuid);
+await sdk.task.complete(uuid, { out: 'done' });
+await sdk.task.fail(uuid, 'error message');
+await sdk.task.start(uuid, { machineId: 'machine-01' });
+```
+
+---
+
+## 3. `sdk.activities.list()` returns `Activity[]` directly — NOT `{ activities: [...] }`
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/activities.ts`  
+**Evidence:** `Return type is Promise<Activity[]>`
+
+**Correct usage:**
+```js
+// ❌ WRONG
+const { activities } = await sdk.activities.list();
+
+// ✅ CORRECT
+const activities = await sdk.activities.list();
+for (const a of activities) { ... }
+```
+
+---
+
+## 4. `sdk.llm.chat()` response is `res.response?.content` — NOT `choices[0].message.content`
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/llm.ts`  
+**Evidence:** `ChatResponse shape: { success, response?: { content, model, metrics } }`
+
+**Correct usage:**
+```js
+// ❌ WRONG (OpenAI style)
+console.log(res.choices[0].message.content);
+
+// ✅ CORRECT
+const res = await sdk.llm.chat([{ role: 'user', content: 'Hello' }]);
+console.log(res.response?.content);
+```
+
+---
+
+## 5. `sdk.llm.chatStream()` yields `chunk.textResponse` — NOT `choices[0].delta.content`
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/llm.ts`  
+**Evidence:** `StreamChunk interface has textResponse?: string`
+
+**Correct usage:**
+```js
+// ❌ WRONG
+chunk.choices?.[0]?.delta?.content
+
+// ✅ CORRECT
+for await (const chunk of sdk.llm.chatStream(messages)) {
+  if (chunk.textResponse) process.stdout.write(chunk.textResponse);
+  if (chunk.close) break;
+}
+```
+
+---
+
+## 6. `sdk.llm.embedAndStore()` takes `{ texts: string[], documentId?, workspaceId?, ... }` — NOT `(text, options)`
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/llm.ts`  
+**Evidence:** `embedAndStore(params: { texts: string[]; documentId?; workspaceId?; ... })`
+
+**Correct usage:**
+```js
+// ❌ WRONG
+await sdk.llm.embedAndStore('text content', { id: 'doc-1' });
+
+// ✅ CORRECT
+await sdk.llm.embedAndStore({ texts: ['chunk 1', 'chunk 2'], documentId: 'doc-1', workspaceId: 'ws-123' });
+```
+
+---
+
+## 7. `sdk.llm.vectors.query()` takes a raw `number[]` embedding — NOT a text string
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/llm.ts`  
+**Evidence:** `query(vector: number[], options?)`
+
+**Correct usage:**
+```js
+// ❌ WRONG
+await sdk.llm.vectors.query('search text');
+
+// ✅ CORRECT — raw vector
+const { embeddings } = await sdk.llm.embed('search text');
+await sdk.llm.vectors.query(embeddings[0], { topK: 5 });
+
+// ✅ EASIER — high-level helper
+const hits = await sdk.llm.search('search text', { topK: 5 });
+```
+
+---
+
+## 8. `sdk.llm.vectors.delete()` requires `{ deleteAll: true }` — delete-by-ID not supported
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/llm.ts`  
+**Evidence:** `VectorDeleteOptions: { workspaceId?, deleteAll: true } (literal true)`
+
+**Correct usage:**
+```js
+// ❌ WRONG
+await sdk.llm.vectors.delete(['id-1', 'id-2']);
+
+// ✅ CORRECT
+await sdk.llm.vectors.delete({ deleteAll: true, workspaceId: 'ws-123' });
+```
+
+---
+
+## 9. `sdk.mcp.getServers()` takes a plain string — NOT `{ provider: "all" }`
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/mcp.ts`  
+**Evidence:** `getServers(provider: 'local' | 'remote' | 'all' = 'all')`
+
+**Correct usage:**
+```js
+// ❌ WRONG
+await sdk.mcp.getServers({ provider: 'all' });
+
+// ✅ CORRECT
+await sdk.mcp.getServers('all');
+await sdk.mcp.getServers();     // defaults to 'all'
+```
+
+---
+
+## 10. `getAgents/getWorkspaces/getThreads/getTask` live on `sdk.api.*` — NOT directly on `sdk.*`
+
+**Status:** 🔴 DETECTED  
+**File:** `index.ts`  
+**Evidence:** `this.api = new ApiModule(...) — separate sub-module in constructor`
+
+**Correct usage:**
+```js
+// ❌ WRONG
+await sdk.getAgents();
+await sdk.getWorkspaces();
+
+// ✅ CORRECT
+await sdk.api.getAgents();
+await sdk.api.getWorkspaces();
+await sdk.api.getThreads('workspace-slug');
+await sdk.api.getTask('task-uuid');
+```
+
+---
+
+## 11. ACP `streamChat` uses named SSE (`event:` line); `text_delta.data.type === "thinking"` = internal reasoning
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/acpAgent.ts`  
+**Evidence:** `Uses parseNamedSSEStream() — reads both event: and data: SSE lines per spec`
+
+**Correct usage:**
+```js
+for await (const event of sdk.acpAgent.streamChat(key, message)) {
+  if (event.type === 'text_delta') {
+    if (event.data.type !== 'thinking') {   // skip internal reasoning
+      process.stdout.write(String(event.data.text ?? ''));
+    }
+  }
+}
+```
+
+---
+
+## 12. ACP sessions stall without `approvalPolicy: "approve-all"` when tools need permission
+
+**Status:** 🔴 DETECTED  
+**File:** `modules/acpAgent.ts`  
+**Evidence:** `AcpSessionOptions.approvalPolicy?: 'approve-all' | 'approve-reads' | 'deny-all'`
+
+**Correct usage:**
+```js
+// ✅ Always set for autonomous scripts
+await sdk.acpAgent.createSession({ agent_id: 'qwen', approvalPolicy: 'approve-all', cwd });
+```
+
+---

package/skills/realtimex-moderator-sdk/scripts/lib/sdk-init.js

@@ -0,0 +1,119 @@
+'use strict';
+/**
+ * sdk-init.js — SDK initializer with automatic credential resolution
+ * AUTO-GENERATED by scripts/generate-skill.mjs — do not edit by hand.
+ *
+ * Source reference: typescript/src/index.ts (RealtimeXSDK constructor)
+ *
+ * Credential resolution priority:
+ *   1. Explicit override passed to initSDK({ apiKey } or { appId })
+ *   2. REALTIMEX_API_KEY / REALTIMEX_AI_API_KEY in <envDir>/.env
+ *   3. RTX_API_KEY / REALTIMEX_API_KEY / REALTIMEX_AI_API_KEY in process.env
+ *   4. RTX_APP_ID in process.env (injected by RealtimeX for agents / local apps)
+ *   5. ~/.realtimex.ai/.sdk-app-id file (written by RealtimeX server on startup)
+ *   6. Interactive readline prompt (dev fallback)
+ */
+
+const path = require('path');
+const fs   = require('fs');
+const os   = require('os');
+const readline = require('readline');
+
+const ALL_PERMISSIONS = [
+  'api.agents', 'api.workspaces', 'api.threads', 'api.task',
+  'webhook.trigger', 'activities.read', 'activities.write',
+  'llm.chat', 'llm.embed', 'llm.providers',
+  'vectors.read', 'vectors.write',
+  'tts.generate', 'mcp.servers', 'mcp.tools', 'acp.agent',
+];
+
+/** Well-known file written by RealtimeX server for seamless SDK auth. */
+const SDK_APP_ID_FILE = path.join(os.homedir(), '.realtimex.ai', '.sdk-app-id');
+
+function parseEnvFile(filePath) {
+  const vars = {};
+  if (!fs.existsSync(filePath)) return vars;
+  for (const raw of fs.readFileSync(filePath, 'utf-8').split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    const val = line.slice(eq + 1).trim().replace(/^["']|["']$/g, '');
+    vars[key] = val;
+  }
+  return vars;
+}
+
+/**
+ * Resolve credentials using the full priority chain.
+ * Returns { apiKey, appId } — exactly one will be set.
+ */
+async function resolveCredentials({ envDir, apiKey, appId } = {}) {
+  // 1. Explicit overrides
+  if (apiKey) return { apiKey, appId: null };
+  if (appId) return { apiKey: null, appId };
+
+  // 2. .env file
+  const envVars = parseEnvFile(path.join(envDir || process.cwd(), '.env'));
+  const fromFile = envVars.REALTIMEX_API_KEY || envVars.REALTIMEX_AI_API_KEY;
+  if (fromFile) return { apiKey: fromFile, appId: null };
+
+  // 3. Process env — API key
+  const fromEnv = process.env.RTX_API_KEY || process.env.REALTIMEX_API_KEY || process.env.REALTIMEX_AI_API_KEY;
+  if (fromEnv) return { apiKey: fromEnv, appId: null };
+
+  // 4. Process env — App ID (injected by RealtimeX for agents / local apps)
+  const envAppId = process.env.RTX_APP_ID;
+  if (envAppId) return { apiKey: null, appId: envAppId };
+
+  // 5. Well-known file (written by RealtimeX server on startup)
+  try {
+    if (fs.existsSync(SDK_APP_ID_FILE)) {
+      const fileAppId = fs.readFileSync(SDK_APP_ID_FILE, 'utf-8').trim();
+      if (fileAppId) return { apiKey: null, appId: fileAppId };
+    }
+  } catch { /* ignore read errors */ }
+
+  // 6. Interactive prompt (dev fallback)
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  const answer = await new Promise((resolve) => {
+    rl.question('RealTimeX API key not found. Enter your API key: ', (ans) => {
+      rl.close();
+      resolve(ans.trim());
+    });
+  });
+  if (answer) return { apiKey: answer, appId: null };
+
+  return { apiKey: null, appId: null };
+}
+
+/** @deprecated Use resolveCredentials() instead */
+async function resolveApiKey(opts = {}) {
+  const { apiKey } = await resolveCredentials(opts);
+  return apiKey;
+}
+
+async function initSDK(opts = {}) {
+  const { RealtimeXSDK } = require('@realtimex/sdk');
+  const { apiKey, appId } = await resolveCredentials(opts);
+
+  if (!apiKey && !appId) {
+    throw new Error(
+      'No credentials found. Set REALTIMEX_API_KEY in .env, or run inside RealtimeX for automatic auth.'
+    );
+  }
+
+  const sdk = new RealtimeXSDK({
+    realtimex: {
+      url: opts.url || 'http://localhost:3001',
+      ...(apiKey ? { apiKey } : {}),
+      ...(appId ? { appId } : {}),
+    },
+    permissions: opts.permissions || ALL_PERMISSIONS,
+  });
+
+  return { sdk, apiKey: apiKey || null, appId: appId || null };
+}
+
+module.exports = { initSDK, resolveCredentials, resolveApiKey, parseEnvFile, ALL_PERMISSIONS, SDK_APP_ID_FILE };