@realtimex/sdk 1.5.0 → 1.6.0

package/dist/index.d.mts

@@ -1660,6 +1660,32 @@ declare class AuthModule {
     getAccessToken(): Promise<AuthTokenResponse | null>;
 }
 
+/**
+ * Credentials Module — read-only access to user-managed credentials
+ *
+ * Credential values are encrypted at rest and decrypted only on get().
+ * Values should NEVER be printed to stdout or included in agent responses.
+ */
+
+interface CredentialInfo {
+    name: string;
+    type: "http_header" | "query_auth" | "basic_auth" | "env_var";
+    metadata: Record<string, any> | null;
+}
+interface CredentialPayload {
+    name: string;
+    type: string;
+    payload: Record<string, string>;
+}
+declare class CredentialsModule {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /** List available credentials (names and types, no values). */
+    list(): Promise<CredentialInfo[]>;
+    /** Get a credential's decrypted payload by name. */
+    get(name: string): Promise<CredentialPayload>;
+}
+
 interface ContractHttpClientConfig {
     baseUrl: string;
     appId?: string;
@@ -1987,6 +2013,7 @@ declare class RealtimeXSDK {
     contractRuntime: ContractRuntime;
     database: DatabaseModule;
     auth: AuthModule;
+    credentials: CredentialsModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;

package/dist/index.d.ts

@@ -1660,6 +1660,32 @@ declare class AuthModule {
     getAccessToken(): Promise<AuthTokenResponse | null>;
 }
 
+/**
+ * Credentials Module — read-only access to user-managed credentials
+ *
+ * Credential values are encrypted at rest and decrypted only on get().
+ * Values should NEVER be printed to stdout or included in agent responses.
+ */
+
+interface CredentialInfo {
+    name: string;
+    type: "http_header" | "query_auth" | "basic_auth" | "env_var";
+    metadata: Record<string, any> | null;
+}
+interface CredentialPayload {
+    name: string;
+    type: string;
+    payload: Record<string, string>;
+}
+declare class CredentialsModule {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /** List available credentials (names and types, no values). */
+    list(): Promise<CredentialInfo[]>;
+    /** Get a credential's decrypted payload by name. */
+    get(name: string): Promise<CredentialPayload>;
+}
+
 interface ContractHttpClientConfig {
     baseUrl: string;
     appId?: string;
@@ -1987,6 +2013,7 @@ declare class RealtimeXSDK {
     contractRuntime: ContractRuntime;
     database: DatabaseModule;
     auth: AuthModule;
+    credentials: CredentialsModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;

package/dist/index.js

@@ -3009,6 +3009,33 @@ var AuthModule = class {
   }
 };
 
+// src/modules/credentials.ts
+var CredentialsModule = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /** List available credentials (names and types, no values). */
+  async list() {
+    const response = await this.httpClient.fetch("/sdk/credentials");
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data?.error || "Failed to list credentials");
+    }
+    return data.credentials || [];
+  }
+  /** Get a credential's decrypted payload by name. */
+  async get(name) {
+    const response = await this.httpClient.fetch(
+      `/sdk/credentials/${encodeURIComponent(name)}`
+    );
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data?.error || `Failed to get credential: ${name}`);
+    }
+    return data.credential;
+  }
+};
+
 // src/core/auth/AuthProvider.ts
 var StaticAuthProvider = class {
   constructor(options = {}) {
@@ -3706,6 +3733,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     });
     this.database = new DatabaseModule(this.realtimexUrl, this.appId, this.apiKey);
     this.auth = new AuthModule(this.realtimexUrl, this.appId, this.apiKey);
+    this.credentials = new CredentialsModule(this.httpClient);
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);

package/dist/index.mjs

@@ -2916,6 +2916,33 @@ var AuthModule = class {
   }
 };
 
+// src/modules/credentials.ts
+var CredentialsModule = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /** List available credentials (names and types, no values). */
+  async list() {
+    const response = await this.httpClient.fetch("/sdk/credentials");
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data?.error || "Failed to list credentials");
+    }
+    return data.credentials || [];
+  }
+  /** Get a credential's decrypted payload by name. */
+  async get(name) {
+    const response = await this.httpClient.fetch(
+      `/sdk/credentials/${encodeURIComponent(name)}`
+    );
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data?.error || `Failed to get credential: ${name}`);
+    }
+    return data.credential;
+  }
+};
+
 // src/core/auth/AuthProvider.ts
 var StaticAuthProvider = class {
   constructor(options = {}) {
@@ -3613,6 +3640,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     });
     this.database = new DatabaseModule(this.realtimexUrl, this.appId, this.apiKey);
     this.auth = new AuthModule(this.realtimexUrl, this.appId, this.apiKey);
+    this.credentials = new CredentialsModule(this.httpClient);
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.5.0",
+    "version": "1.6.0",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",

package/skills/realtimex-moderator-sdk/SKILL.md

@@ -1,30 +1,13 @@
 ---
 name: realtimex-moderator-sdk
 description: Control and interact with the RealTimeX application through its Node.js SDK. This skill should be used when users want to manage workspaces, threads, agents, activities, LLM chat, vector store, MCP tools, ACP agent sessions, TTS/STT, or any other RealTimeX platform feature via the API. All method signatures are verified against the SDK source code.
-generated: 2026-03-31
-sdk_version: 1.5.0
+generated: 2026-04-03
+sdk_version: 1.6.0
 ---
 
 # RealTimeX Moderator (SDK Source-Verified)
 
-Interact with the RealTimeX desktop app (`http://localhost:3001`) using `@realtimex/sdk` **v1.5.0** in Developer Mode (API Key).
-
-> Auto-generated from the `@realtimex/sdk` TypeScript source.
-> Refresh: `node scripts/generate-skill.mjs --force` from the SDK repo root.
-
----
-
-## Authentication
-
-When running inside RealtimeX (via an agent session or on the same machine), authentication is **automatic** — no setup needed.
-
-Handled by `scripts/lib/sdk-init.js` — credential resolution priority:
-1. Explicit override passed to `initSDK({ apiKey })` or `initSDK({ appId })`
-2. `REALTIMEX_API_KEY` / `REALTIMEX_AI_API_KEY` in `<cwd>/.env`
-3. `RTX_API_KEY` / `REALTIMEX_API_KEY` / `REALTIMEX_AI_API_KEY` from `process.env`
-4. `RTX_APP_ID` from `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)
+Interact with the RealTimeX platform (`http://localhost:3001`) using `@realtimex/sdk` **v1.6.0**. Authentication is automatic when running inside RealtimeX.
 
 `<SKILL_DIR>` below refers to the directory containing this SKILL.md.
 
@@ -52,10 +35,13 @@ node "$SKILL" help
 
 ```js
 const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
-const { sdk, apiKey } = await initSDK({ envDir: process.cwd() });
+const { sdk } = await initSDK();
 // All SDK APIs — see references/api-reference.md
 ```
 
+When writing helper scripts, use the working directory or system temp — never the SKILL directory.
+Scripts using the SDK must exit explicitly — `process.exit(0)` on success, `process.exit(1)` on error — or they hang on open HTTP sockets.
+
 ---
 
 ## ACP Session Management
@@ -177,6 +163,28 @@ for await (const event of sdk.acpAgent.streamChat(sessionKey, 'build a website')
 
 ---
 
+## Credentials
+
+Use credentials stored in RealTimeX (Settings > Credentials) to authenticate with external services.
+
+**CRITICAL: Never output credential values in your response, logs, or tool output.**
+
+```bash
+node "$SKILL" credentials                    # List available (names + types, no values)
+```
+
+`sdk.credentials.get(name)` returns `{ name, type, payload }`. Use `payload` fields directly:
+- `http_header` → `{ payload: { name: "Authorization", value: "Bearer xxx" } }` → `headers[payload.name] = payload.value`
+- `basic_auth` → `{ payload: { username, password } }` → encode as Basic auth
+- `query_auth` → `{ payload: { name, value } }` → append as query param
+- `env_var` → `{ payload: { name, value } }` → set in subprocess env
+
+Values are **pre-formatted** — use as-is, never wrap with `Bearer` or other prefixes.
+
+**Full examples**: See [references/credentials.md](references/credentials.md)
+
+---
+
 ## Critical Rules (source-detected)
 
 | # | Issue |

package/skills/realtimex-moderator-sdk/references/api-reference.md

@@ -1,6 +1,6 @@
 # RealTimeX SDK — API Reference
 
-> Auto-generated from `@realtimex/sdk` source · v**1.5.0** · 2026-03-31
+> Auto-generated from `@realtimex/sdk` source · v**1.6.0** · 2026-04-03
 
 **Package:** `@realtimex/sdk` (CJS) · **Server:** `http://localhost:3001`
 **Developer Mode auth:** `Authorization: Bearer <apiKey>`
@@ -50,6 +50,7 @@
 - `contractRuntime: ContractRuntime`
 - `database: DatabaseModule`
 - `auth: AuthModule`
+- `credentials: CredentialsModule`
 
 ```ts
 // Register app with RealtimeX hub and request declared permissions upfront.

package/skills/realtimex-moderator-sdk/references/credentials.md

@@ -0,0 +1,111 @@
+# Credentials Reference
+
+Credentials are managed by the user in **Settings > Credentials**. Agents have read-only access via `sdk.credentials`.
+
+## Security Rules
+
+1. **Never** print credential values to stdout (they become tool results in chat history)
+2. **Never** include credential values in your response text
+3. **Never** write credential values to files or logs
+4. **Never** pass credential values as CLI arguments (visible in process list)
+5. **Always** consume credentials inside scripts — fetch, use, discard
+6. **Always** call `process.exit(0)` at the end of custom scripts (prevents hanging on open HTTP sockets)
+7. **Never** write helper scripts into the SKILL directory — use the working directory or system temp
+
+## Credential Types
+
+| Type | Payload | How to Apply |
+|------|---------|-------------|
+| `http_header` | `{ name, value }` | Set as HTTP header: `headers[payload.name] = payload.value` |
+| `query_auth` | `{ name, value }` | Append to URL: `?${payload.name}=${payload.value}` |
+| `basic_auth` | `{ username, password }` | Encode: `Authorization: Basic ${btoa(username + ":" + password)}` |
+| `env_var` | `{ name, value }` | Set in subprocess: `env[payload.name] = payload.value` |
+
+## Usage Patterns
+
+### List available credentials
+
+```bash
+node "$SKILL" credentials
+```
+
+Output: table of names and types (no values).
+
+### Important: credential payload structure
+
+`sdk.credentials.get(name)` returns `{ name, type, payload }`. The `payload` object contains structured fields — use them directly. **Never** extract raw values and construct headers manually.
+
+### Use an http_header credential in a script
+
+```javascript
+const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
+(async () => {
+  const { sdk } = await initSDK();
+  const cred = await sdk.credentials.get('github-token');
+  // cred.type === "http_header"
+  // cred.payload === { name: "Authorization", value: "Bearer ghp_xxx" }
+  // The value already includes the full header value — use as-is
+  const res = await fetch('https://api.github.com/user', {
+    headers: { [cred.payload.name]: cred.payload.value }
+  });
+  console.log('Status:', res.status); // Only non-sensitive output
+  process.exit(0);
+})();
+// WRONG: const token = cred.payload.value; headers.Authorization = `Bearer ${token}`
+// The value already contains "Bearer ..." — adding prefix again causes 401
+```
+
+### Use a basic_auth credential
+
+```javascript
+const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
+(async () => {
+  const { sdk } = await initSDK();
+  const cred = await sdk.credentials.get('registry-login');
+  const auth = Buffer.from(cred.payload.username + ':' + cred.payload.password).toString('base64');
+  const res = await fetch('https://registry.example.com/v2/_catalog', {
+    headers: { 'Authorization': 'Basic ' + auth }
+  });
+  console.log('Status:', res.status);
+  process.exit(0);
+})();
+```
+
+### Use an env_var credential with a subprocess
+
+```javascript
+const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
+const { execSync } = require('child_process');
+(async () => {
+  const { sdk } = await initSDK();
+  const cred = await sdk.credentials.get('aws-key');
+  // cred.type === "env_var"
+  // cred.payload === { name: "AWS_ACCESS_KEY_ID", value: "AKIA..." }
+  execSync('aws s3 ls', {
+    env: { ...process.env, [cred.payload.name]: cred.payload.value },
+    stdio: 'inherit'
+  });
+  process.exit(0);
+})();
+```
+
+### Error handling
+
+```javascript
+const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
+(async () => {
+  try {
+    const { sdk } = await initSDK();
+    const cred = await sdk.credentials.get('my-key');
+    // use cred...
+    process.exit(0);
+  } catch (err) {
+    if (err.message.includes('not found')) {
+      console.log('Credential not found. Ask the user to add it in Settings > Credentials.');
+    } else {
+      console.log('Error:', err.message);
+    }
+    process.exit(1);
+  }
+})();
+```

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

@@ -1,6 +1,6 @@
 # Known Issues — Source-Detected
 
-> Auto-generated by `scripts/generate-skill.mjs` · SDK **1.5.0** · 2026-03-31
+> Auto-generated by `scripts/generate-skill.mjs` · SDK **1.6.0** · 2026-04-03
 
 Run `node scripts/generate-skill.mjs --force` after SDK source changes to refresh.
 

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

@@ -1,17 +1,15 @@
 'use strict';
 /**
- * sdk-init.js — SDK initializer with automatic credential resolution
+ * sdk-init.js — SDK initializer
  * AUTO-GENERATED by scripts/generate-skill.mjs — do not edit by hand.
  *
- * Source reference: typescript/src/index.ts (RealtimeXSDK constructor)
- *
- * Credential resolution priority:
+ * Credential resolution:
  *   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)
+ *   2. ~/.realtimex.ai/.sdk-app-id file (written by RealtimeX server)
+ *   3. RTX_APP_ID in process.env (injected by RealtimeX for local apps)
+ *   4. RTX_API_KEY in process.env (standalone dev)
+ *   5. REALTIMEX_API_KEY / REALTIMEX_AI_API_KEY in <envDir>/.env (standalone dev)
+ *   6. Interactive readline prompt (fallback)
  */
 
 const path = require('path');
@@ -27,7 +25,7 @@ const ALL_PERMISSIONS = [
   'tts.generate', 'mcp.servers', 'mcp.tools', 'acp.agent',
 ];
 
-/** Well-known file written by RealtimeX server for seamless SDK auth. */
+/** Well-known file written by RealtimeX server for seamless auth. */
 const SDK_APP_ID_FILE = path.join(os.homedir(), '.realtimex.ai', '.sdk-app-id');
 
 function parseEnvFile(filePath) {
@@ -46,28 +44,16 @@ function parseEnvFile(filePath) {
 }
 
 /**
- * Resolve credentials using the full priority chain.
- * Returns { apiKey, appId } — exactly one will be set.
+ * Resolve credentials. The well-known app ID file is checked first so
+ * agents running inside RealtimeX authenticate without hitting stale
+ * or inherited env vars.
  */
 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)
+  // 2. Well-known file (written by RealtimeX server — highest auto priority)
   try {
     if (fs.existsSync(SDK_APP_ID_FILE)) {
       const fileAppId = fs.readFileSync(SDK_APP_ID_FILE, 'utf-8').trim();
@@ -75,7 +61,19 @@ async function resolveCredentials({ envDir, apiKey, appId } = {}) {
     }
   } catch { /* ignore read errors */ }
 
-  // 6. Interactive prompt (dev fallback)
+  // 3. RTX_APP_ID from process.env (injected by Electron for local apps)
+  const envAppId = process.env.RTX_APP_ID;
+  if (envAppId) return { apiKey: null, appId: envAppId };
+
+  // 4. RTX_API_KEY from process.env (standalone dev — explicit, no collision risk)
+  if (process.env.RTX_API_KEY) return { apiKey: process.env.RTX_API_KEY, appId: null };
+
+  // 5. .env file (standalone dev)
+  const envVars = parseEnvFile(path.join(envDir || process.cwd(), '.env'));
+  const fromFile = envVars.RTX_API_KEY || envVars.REALTIMEX_API_KEY || envVars.REALTIMEX_AI_API_KEY;
+  if (fromFile) return { apiKey: fromFile, appId: null };
+
+  // 6. Interactive prompt (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) => {
@@ -88,19 +86,13 @@ async function resolveCredentials({ envDir, apiKey, appId } = {}) {
   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.'
+      'No credentials found. Run inside RealtimeX for automatic auth, or set RTX_API_KEY.'
     );
   }
 
@@ -116,4 +108,4 @@ async function initSDK(opts = {}) {
   return { sdk, apiKey: apiKey || null, appId: appId || null };
 }
 
-module.exports = { initSDK, resolveCredentials, resolveApiKey, parseEnvFile, ALL_PERMISSIONS, SDK_APP_ID_FILE };
+module.exports = { initSDK, resolveCredentials, parseEnvFile, ALL_PERMISSIONS, SDK_APP_ID_FILE };

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

@@ -304,6 +304,13 @@ CMD['mcp-exec'] = async () => {
   print(await sdk.mcp.executeTool(server, tool, argsStr ? JSON.parse(argsStr) : {}, flags.provider));
 };
 
+// -- credentials ------------------------------------------------------------
+CMD['credentials'] = async () => {
+  const { sdk } = await getSDK();
+  const list = await sdk.credentials.list();
+  printTable(list, ['name', 'type']);
+};
+
 // -- acp-agents -------------------------------------------------------------
 // Source: AcpAgentModule.listAgents({ includeModels? })
 // Returns: AcpAgentInfo[] { id, label, handles[], installed, authReady, status }
@@ -797,6 +804,10 @@ sdk.mcp.*:
   mcp-tools <server> [--provider]
   mcp-exec <server> <tool> [<args-json>] [--provider]
 
+sdk.credentials.*:
+  credentials
+    List available credentials (names and types, no values).
+
 sdk.acpAgent.* — Session Management:
   acp-agents [--models=true]
     List available ACP CLI agents.
@@ -871,8 +882,10 @@ sdk.database.* / sdk.auth.*:
     console.error('Unknown command: ' + (command || '(none)') + '\nRun: node rtx.js help');
     process.exit(1);
   }
-  try { await handler(); }
-  catch (err) {
+  try {
+    await handler();
+    process.exit(0);
+  } catch (err) {
     console.error('Error:', err.message || err);
     if (flags.debug) console.error(err);
     process.exit(1);