@realtimex/sdk 1.7.17 → 1.7.21

package/skills/realtimex-moderator-sdk/references/app-concepts.md

@@ -204,6 +204,7 @@ A platform user account.
 | `dailyMessageLimit` | Int? | — | — |
 | `bio` | String? |  | — |
 | `workspace_chats` | workspace_chats[] | — | — |
+| `terminal_ui_events` | terminal_ui_events[] | — | — |
 | `workspace_users` | workspace_users[] | — | — |
 | `created_workspaces` | workspaces[] | — | — |
 | `embed_configs` | embed_configs[] | — | — |
@@ -247,6 +248,7 @@ A chat/knowledge space with its own documents, LLM config, and agent settings.
 | `similarityThreshold` | Float? | 0.25 | — |
 | `chatProvider` | String? | — | — |
 | `chatModel` | String? | — | — |
+| `chatTuningConfig` | String? | — | — |
 | `topN` | Int? | 4 | — |
 | `chatMode` | String? | chat | — |
 | `pfpFilename` | String? | — | — |
@@ -288,6 +290,11 @@ A chat/knowledge space with its own documents, LLM config, and agent settings.
 | `knowledgeConfig` | String? | — | — |
 | `type` | String? | default | — |
 | `workspace_tasks` | workspace_tasks[] | — | — |
+| `goal_sources` | goal_sources[] | — | — |
+| `goal_runs` | goal_runs[] | — | — |
+| `goal_events` | goal_events[] | — | — |
+| `goal_artifacts` | goal_artifacts[] | — | — |
+| `terminal_ui_events` | terminal_ui_events[] | — | — |
 | `channel_plugins` | channel_plugins[] | — | — |
 | `agentic_cli_workspace_overrides` | agentic_cli_workspace_overrides[] | — | — |
 
@@ -356,6 +363,7 @@ A conversation thread within a workspace. Can represent a meeting or a standalon
 | `user_id` | Int? | — | — |
 | `chatProvider` | String? | — | — |
 | `chatModel` | String? | — | — |
+| `chatTuningConfig` | String? | — | — |
 | `meeting_source` | String? | manual | — |
 | `meeting_status` | String? | draft | — |
 | `scheduled_start_at` | DateTime? | — | — |
@@ -373,6 +381,10 @@ A conversation thread within a workspace. Can represent a meeting or a standalon
 | `meeting_outputs` | meeting_outputs[] | — | — |
 | `workspace_parsed_files` | workspace_parsed_files[] | — | — |
 | `workspace_tasks` | workspace_tasks[] | — | — |
+| `goal_sources` | goal_sources[] | — | — |
+| `goal_runs` | goal_runs[] | — | — |
+| `goal_events` | goal_events[] | — | — |
+| `goal_artifacts` | goal_artifacts[] | — | — |
 
 ### workspace_chats (`workspace_chats`)
 | Field | Type | Default | Notes |
@@ -388,6 +400,24 @@ A conversation thread within a workspace. Can represent a meeting or a standalon
 | `feedbackScore` | Boolean? | — | — |
 | `users` | users? | — | — |
 
+### terminal_ui_events (`terminal_ui_events`)
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `workspaceId` | Int | — | — |
+| `scope_key` | String | — | — |
+| `event_key` | String | — | — |
+| `type` | String | — | — |
+| `domain` | String? | — | — |
+| `content` | String | — | — |
+| `assistant_agent` | String? | — | — |
+| `source_chat_id` | Int? | — | — |
+| `user_id` | Int? | — | — |
+| `thread_id` | Int? | — | — |
+| `api_session_id` | String? | — | — |
+| `occurredAt` | DateTime? | — | — |
+| `workspace` | workspaces | — | — |
+| `user` | users? | — | — |
+
 ### AgentInvocation (`workspace_agent_invocations`)
 A single agent task invocation with lifecycle state tracking.
 
@@ -830,6 +860,124 @@ A discrete task created within a workspace.
 | `user` | users? | — | — |
 | `thread` | workspace_threads? | — | — |
 
+### goals (`goals`)
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `uuid` | String | uuid( | — |
+| `goal_key` | String | — | — |
+| `title` | String | — | — |
+| `description` | String? | — | — |
+| `status` | String | idle | idle, running, due, acted, blocked, disabled, achieved |
+| `priority` | String? | normal | — |
+| `last_run_at` | DateTime? | — | — |
+| `last_achieved_at` | DateTime? | — | — |
+| `metadata` | String? | — | — |
+| `created_at` | DateTime | now( | — |
+| `updated_at` | DateTime | — | — |
+| `sources` | goal_sources[] | — | — |
+| `runs` | goal_runs[] | — | — |
+| `events` | goal_events[] | — | — |
+| `artifacts` | goal_artifacts[] | — | — |
+
+### goal_sources (`goal_sources`)
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `uuid` | String | uuid( | — |
+| `goal_id` | Int | — | — |
+| `source_type` | String | — | — |
+| `source_ref` | String | — | — |
+| `workspace_id` | Int? | — | — |
+| `thread_id` | Int? | — | — |
+| `metadata` | String? | — | — |
+| `created_at` | DateTime | now( | — |
+| `updated_at` | DateTime | — | — |
+| `goal` | goals | — | — |
+| `workspace` | workspaces? | — | — |
+| `thread` | workspace_threads? | — | — |
+| `runs` | goal_runs[] | — | — |
+| `events` | goal_events[] | — | — |
+
+### goal_runs (`goal_runs`)
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `uuid` | String | uuid( | — |
+| `goal_id` | Int | — | — |
+| `goal_source_id` | Int? | — | — |
+| `run_role` | String | monitoring | — |
+| `workspace_id` | Int? | — | — |
+| `thread_id` | Int? | — | — |
+| `thread_slug` | String? | — | — |
+| `task_session_key` | String? | — | — |
+| `status` | String | running | running, acted, no_action, error, blocked, achieved |
+| `trigger` | String? | — | — |
+| `started_at` | DateTime | — | — |
+| `completed_at` | DateTime? | — | — |
+| `message_preview` | String? | — | — |
+| `error` | String? | — | — |
+| `activity_card_id` | String? | — | — |
+| `runtime_session_id` | String? | — | — |
+| `executor_agent` | String? | — | — |
+| `executor_type` | String? | — | — |
+| `executor_provider_id` | String? | — | — |
+| `executor_model` | String? | — | — |
+| `metadata` | String? | — | — |
+| `created_at` | DateTime | now( | — |
+| `updated_at` | DateTime | — | — |
+| `goal` | goals | — | — |
+| `source` | goal_sources? | — | — |
+| `workspace` | workspaces? | — | — |
+| `thread` | workspace_threads? | — | — |
+| `events` | goal_events[] | — | — |
+| `artifacts` | goal_artifacts[] | — | — |
+
+### goal_events (`goal_events`)
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `uuid` | String | uuid( | — |
+| `goal_id` | Int | — | — |
+| `goal_source_id` | Int? | — | — |
+| `goal_run_id` | Int? | — | — |
+| `activity_role` | String? | — | — |
+| `workspace_id` | Int? | — | — |
+| `thread_id` | Int? | — | — |
+| `thread_slug` | String? | — | — |
+| `event_type` | String | — | — |
+| `activity_card_id` | String? | — | — |
+| `runtime_session_id` | String? | — | — |
+| `payload` | String? | — | — |
+| `occurred_at` | DateTime | — | — |
+| `created_at` | DateTime | now( | — |
+| `goal` | goals | — | — |
+| `source` | goal_sources? | — | — |
+| `run` | goal_runs? | — | — |
+| `workspace` | workspaces? | — | — |
+| `thread` | workspace_threads? | — | — |
+
+### goal_artifacts (`goal_artifacts`)
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `uuid` | String | uuid( | — |
+| `goal_id` | Int | — | — |
+| `goal_run_id` | Int? | — | — |
+| `workspace_id` | Int? | — | — |
+| `thread_id` | Int? | — | — |
+| `thread_slug` | String? | — | — |
+| `activity_role` | String? | — | — |
+| `artifact_role` | String | supporting | supporting, completion |
+| `artifact_type` | String | file | file, report, document, output |
+| `label` | String | — | — |
+| `path` | String | — | — |
+| `is_absolute` | Boolean | false | — |
+| `activity_card_id` | String? | — | — |
+| `runtime_session_id` | String? | — | — |
+| `metadata` | String? | — | — |
+| `created_at` | DateTime | now( | — |
+| `updated_at` | DateTime | — | — |
+| `goal` | goals | — | — |
+| `run` | goal_runs? | — | — |
+| `workspace` | workspaces? | — | — |
+| `thread` | workspace_threads? | — | — |
+
 ### ChannelPlugin (`channel_plugins`)
 A messaging channel integration (e.g. Slack, Teams) linked to a workspace.
 

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

@@ -0,0 +1,27 @@
+# RealTimeX Browser
+
+> Generated workflow guide · SDK **1.7.21** · 2026-05-18
+
+Use this for managed RealTimeX Browser sessions and tabs.
+
+Correct namespace:
+
+```js
+sdk.desktopBrowser
+```
+
+Preferred flow:
+1. Create or get a named browser session.
+2. Read its `remoteDebugPort`.
+3. Use the `agent-browser` skill against that CDP port for page interaction.
+
+```js
+await sdk.desktopBrowser.createSession({ sessionName: "docs-research" });
+await sdk.desktopBrowser.createTab({
+  sessionName: "docs-research",
+  url: "https://example.com"
+});
+const session = await sdk.desktopBrowser.getSession("docs-research");
+```
+
+Avoid mutating reserved `acp-*` browser sessions unless the user explicitly asks for internal ACP browser flows.

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

@@ -0,0 +1,189 @@
+# External Chat Channels
+
+> Generated workflow guide · SDK **1.7.21** · 2026-05-18
+
+Use this for Telegram, Zalo, WhatsApp, Discord, Slack, and other chat channel setup.
+
+Required LocalApp permission for `x-app-id` mode:
+
+```js
+permissions: ["channels.manage"]
+```
+
+Main namespace:
+
+```js
+sdk.v1.channels
+```
+
+## Agent Setup Rules
+
+- Never print bot tokens, credentials, QR auth state, or full config values back to chat.
+- Do not guess workspace or thread. Load `skills get workspaces` if context is missing.
+- Ask the user to complete provider-side steps that cannot be automated, such as BotFather setup or QR scanning.
+- Prefer creating plugins disabled first, then start only after credentials/login/policies are ready.
+- Use `settings.thread_id` only when the user explicitly wants messages routed to a specific thread.
+- Use `agentWhitelist: ["*"]` only when the user wants any mentioned/available agent allowed. Otherwise ask which agents should be allowed.
+
+## Decision Tree
+
+- User says Telegram: ask for workspace and Telegram bot token. If they do not have a token, tell them to create one in BotFather first.
+- User says WhatsApp: create a `whatsapp` plugin with empty config, start QR login, ask the user to scan, poll state, configure policies, then start.
+- User says Zalo personal: create a `zalo_personal` plugin with empty config, start QR login, ask the user to scan, poll state, configure policies, then start.
+- User asks to restrict access: use pairing codes or provider policies.
+- User asks to allow anyone: set permissive policies only after confirming the security tradeoff.
+- User is unsure which provider: list supported values: `telegram`, `slack`, `discord`, `zalo`, `zalo_personal`, `whatsapp`.
+
+## Common Flow
+
+1. Resolve workspace and optional target thread.
+2. Identify provider and collect only the needed credential or QR action.
+3. For token providers, call `pluginsTest(...)` before creating when supported.
+4. Create plugin with `createPlugin(...)` and `enabled: false`.
+5. For QR providers, call `pluginsQrLoginStart(...)`, ask the user to scan, then poll `getState(...)` until connected or failed.
+6. Configure policies with `pluginsPolicies(...)` where relevant.
+7. Start with `pluginsStart(...)`.
+8. Verify `getStatus()` and ask the user to send a first message from the external platform.
+
+## Telegram Bot
+
+Provider-side step: the user must create a Telegram bot with BotFather and provide the bot token.
+
+Test credentials:
+
+```js
+await sdk.v1.channels.pluginsTest({
+  plugin_type: "telegram",
+  config: { botToken: process.env.TELEGRAM_BOT_TOKEN }
+});
+```
+
+Create plugin:
+
+```js
+const created = await sdk.v1.channels.createPlugin({
+  workspace_id: 1,
+  plugin_type: "telegram",
+  name: "Support Telegram",
+  enabled: false,
+  config: { botToken: process.env.TELEGRAM_BOT_TOKEN },
+  settings: { thread_id: null, agentWhitelist: ["*"] }
+});
+await sdk.v1.channels.pluginsStart(String(created.plugin.id));
+```
+
+First-message check: ask the user to open Telegram, start the bot, and send a test message.
+
+## WhatsApp QR
+
+Provider-side step: the user must scan the QR code with WhatsApp.
+
+```js
+const created = await sdk.v1.channels.createPlugin({
+  workspace_id: 1,
+  plugin_type: "whatsapp",
+  name: "WhatsApp",
+  enabled: false,
+  config: {},
+  settings: { thread_id: null, agentWhitelist: ["*"] }
+});
+
+const id = String(created.plugin.id);
+await sdk.v1.channels.pluginsQrLoginStart(id, { force: false });
+
+// Poll until status.connected is true, status.status is error, or user cancels.
+const state = await sdk.v1.channels.getState(id);
+
+await sdk.v1.channels.pluginsPolicies(id, {
+  policies: {
+    dmPolicy: "pairing",
+    groupPolicy: "disabled",
+    selfChatMode: false
+  }
+});
+
+await sdk.v1.channels.pluginsStart(id);
+```
+
+Policy guidance:
+- `dmPolicy: "pairing"` is safer for private access.
+- Keep `groupPolicy: "disabled"` unless the user explicitly wants group chat support.
+- Enable `selfChatMode` only when the user understands the loop/testing behavior.
+
+## Zalo Personal QR
+
+Provider-side step: the user must scan the QR code with Zalo.
+
+```js
+const created = await sdk.v1.channels.createPlugin({
+  workspace_id: 1,
+  plugin_type: "zalo_personal",
+  name: "Zalo Personal",
+  enabled: false,
+  config: {},
+  settings: { thread_id: null, agentWhitelist: ["*"] }
+});
+
+const id = String(created.plugin.id);
+await sdk.v1.channels.pluginsQrLoginStart(id, { force: false });
+const state = await sdk.v1.channels.getState(id);
+
+await sdk.v1.channels.pluginsPolicies(id, {
+  policies: {
+    dmPolicy: "pairing",
+    groupPolicy: "disabled",
+    requireMention: false,
+    allowFrom: [],
+    groups: {}
+  }
+});
+
+await sdk.v1.channels.pluginsStart(id);
+```
+
+Directory helpers after login:
+
+```js
+await sdk.v1.channels.listDirectoryFriends(id);
+await sdk.v1.channels.listDirectoryGroups(id);
+```
+
+## Pairing And User Approval
+
+Use pairing when the channel should not allow every external user by default.
+
+```js
+const code = await sdk.v1.channels.pluginsPairingCodes(pluginId, {
+  platform_user_id: "external-user-id",
+  platform_username: "Customer Name"
+});
+
+await sdk.v1.channels.listPluginPairingCodes(pluginId);
+await sdk.v1.channels.pairingCodesApprove(String(code.code.id));
+await sdk.v1.channels.listPluginUsers(pluginId);
+await sdk.v1.channels.pluginsUsersAuthorization(pluginId, userId, { authorized: true });
+```
+
+## Status And Troubleshooting
+
+```js
+await sdk.v1.channels.listPlugins();
+await sdk.v1.channels.getStatus();
+await sdk.v1.channels.getConfig(pluginId);
+```
+
+- `Not authenticated`: QR login did not complete or credentials were cleared. Start QR login again.
+- Start fails: stop the plugin, test credentials if token-based, check `getStatus()`, then start again.
+- User cannot chat: check pairing codes, user authorization, `dmPolicy`, `groupPolicy`, and provider allow lists.
+- Messages route to the wrong place: check `workspace_id` and `settings.thread_id`.
+- Bot does not receive external messages: confirm provider-side webhook/session requirements and that the plugin is running.
+
+## Cleanup
+
+```js
+await sdk.v1.channels.pluginsStop(pluginId);
+await sdk.v1.channels.pluginsLogout(pluginId); // QR providers only
+await sdk.v1.channels.deletePlugin(pluginId);
+```
+
+Exact generated methods are in `api-reference/v1-channels.md`.

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.7.17** · 2026-05-11
+> Auto-generated by `scripts/generate-skill.mjs` · SDK **1.7.21** · 2026-05-18
 
 Run `node scripts/generate-skill.mjs --force` after SDK source changes to refresh.
 

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

@@ -0,0 +1,13 @@
+# LLM And Vector Store
+
+> Generated workflow guide · SDK **1.7.21** · 2026-05-18
+
+Use `sdk.llm` for chat, streaming, embeddings, and vector helpers.
+
+Common permissions: `llm.chat`, `llm.embed`, `llm.providers`, `vectors.read`, `vectors.write`.
+
+```js
+await sdk.llm.chat([{ role: "user", content: "Hello" }]);
+await sdk.llm.embed(["text to embed"]);
+await sdk.llm.vectors.query(vector, { workspaceId });
+```

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

@@ -0,0 +1,13 @@
+# MCP
+
+> Generated workflow guide · SDK **1.7.21** · 2026-05-18
+
+Use `sdk.mcp` to list MCP servers, list tools, and execute tools.
+
+Required permissions: `mcp.servers` and `mcp.tools`.
+
+```js
+await sdk.mcp.getServers();
+await sdk.mcp.getTools(serverName);
+await sdk.mcp.executeTool(serverName, toolName, args);
+```

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

@@ -0,0 +1,30 @@
+# Permissions
+
+> Generated workflow guide · SDK **1.7.21** · 2026-05-18
+
+LocalApps using `x-app-id` must request permissions before calling protected SDK routes.
+
+| Permission | Use For |
+|---|---|
+| `api.agents` | List agents |
+| `api.workspaces` | List workspaces |
+| `api.threads` | List workspace threads |
+| `api.task` | Read task status |
+| `activities.read` | Read activities |
+| `activities.write` | Create/update/delete activities |
+| `llm.chat` | LLM chat and streaming chat |
+| `llm.embed` | Generate embeddings |
+| `llm.providers` | List LLM/embed providers |
+| `vectors.read` | Query/list vector stores |
+| `vectors.write` | Upsert/delete vectors |
+| `mcp.servers` | List MCP servers |
+| `mcp.tools` | List/execute MCP tools |
+| `acp.agent` | ACP agent sessions |
+| `desktop.runtime-sessions` | Visible Electron terminal sessions |
+| `desktop.browser` | RealTimeX Browser sessions and tabs |
+| `channels.manage` | External chat channel setup and administration |
+| `tts.generate` | Text-to-speech |
+| `stt.listen` | Speech-to-text |
+| `credentials.read` | Read stored credentials |
+
+API-key dev mode has wildcard access.

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

@@ -0,0 +1,16 @@
+# Quickstart
+
+> Generated workflow guide · SDK **1.7.21** · 2026-05-18
+
+Use this when starting any SDK task.
+
+```js
+const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
+const { sdk, context } = await initSDK();
+```
+
+Rules:
+- Use the working directory or system temp for helper scripts, never the skill directory.
+- Exit scripts explicitly with `process.exit(0)` or `process.exit(1)`.
+- Check `context.workspaceSlug` and `context.threadSlug` before asking the user.
+- For exact signatures, open `references/api-reference/index.md`.

package/skills/realtimex-moderator-sdk/references/terminal-sessions.md

@@ -0,0 +1,34 @@
+# Desktop Terminal Sessions
+
+> Generated workflow guide · SDK **1.7.21** · 2026-05-18
+
+Use this for visible Electron terminal sessions.
+
+Correct namespace:
+
+```js
+sdk.desktopRuntimeSessions
+```
+
+Do not use ACP for visible terminals unless the user explicitly asks for headless ACP.
+
+Examples:
+
+```js
+await sdk.desktopRuntimeSessions.launchTerminalCliAgent({
+  workspaceSlug,
+  threadSlug,
+  agentName: "claude",
+  providerId: "claude-cli",
+  presentationMode: "panel",
+  message: "what is current working dir"
+});
+
+await sdk.desktopRuntimeSessions.launchTerminalShell({
+  workspaceSlug,
+  threadSlug,
+  presentationMode: "panel",
+  initialCommand: "pwd",
+  initialCommandMode: "direct"
+});
+```

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

@@ -0,0 +1,20 @@
+# Workspaces And Threads
+
+> Generated workflow guide · SDK **1.7.21** · 2026-05-18
+
+Use this before any task that needs workspace/thread context.
+
+Priority order:
+1. Explicit user-provided workspace/thread.
+2. `context.workspaceSlug` / `context.threadSlug` from `initSDK()`.
+3. `RTX_WORKSPACE_SLUG` / `RTX_THREAD_SLUG` in spawned sessions.
+4. List workspaces and threads, then ask only if ambiguous.
+
+Useful calls:
+
+```js
+await sdk.api.getWorkspaces();
+await sdk.api.getThreads(workspaceSlug);
+await sdk.v1.workspace.listWorkspaces();
+await sdk.v1.thread.listWorkspaceThreads(slug);
+```