@realtimex/sdk 1.7.14 → 1.7.16

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.7.14",
+    "version": "1.7.16",
     "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

@@ -2,12 +2,12 @@
 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-05-08
-sdk_version: 1.7.14
+sdk_version: 1.7.16
 ---
 
 # RealTimeX Moderator (SDK Source-Verified)
 
-Interact with the RealTimeX platform (`http://localhost:3001`) using `@realtimex/sdk` **v1.7.14**. Authentication is automatic when running inside RealtimeX.
+Interact with the RealTimeX platform (`http://localhost:3001`) using `@realtimex/sdk` **v1.7.16**. Authentication is automatic when running inside RealtimeX.
 
 `<SKILL_DIR>` below refers to the directory containing this SKILL.md.
 
@@ -177,6 +177,7 @@ If the user says:
 - "create a browser session"
 - "navigate the managed browser tab"
 - "focus or close a RealTimeX Browser tab"
+- "control the webpage in the browser"
 
 then prefer `sdk.desktopBrowser.*`, not ACP and not desktop terminal sessions.
 
@@ -194,13 +195,30 @@ Do **not** use ACP for this unless the user explicitly wants ACP browser handoff
 - listing named RealTimeX Browser sessions
 - creating a named browser session
 - getting or deleting a named browser session
-- creating a browser tab in a named session
+- opening the initial URL for a new browser session
 - reading a browser tab snapshot
 - evaluating JavaScript in a browser tab
 - focusing a browser tab
 - navigating a browser tab
 - closing a browser tab
 
+### Current workflow rule
+
+The current CLI browser flow has a known problem when opening another URL in a new managed tab.
+
+Because of that:
+- if the user needs a different URL, create a new browser session first
+- do not rely on opening another managed tab as the primary workflow
+- treat one named browser session as one main browsing target
+
+Preferred flow:
+1. create a named browser session
+2. read the returned `remoteDebugPort`
+3. use the `agent-browser` skill against that CDP port for page interaction and automation
+
+Use `sdk.desktopBrowser.*` to create/list/get/delete the session.
+Use `agent-browser` to manipulate the webpage after the session is running.
+
 ### Correct SDK namespace
 
 ```js
@@ -236,6 +254,13 @@ await sdk.desktopBrowser.createTab({
 });
 ```
 
+Get the CDP port from a session:
+
+```js
+const session = await sdk.desktopBrowser.getSession("github-review");
+const port = session?.session?.remoteDebugPort || session?.runtime?.remoteDebugPort;
+```
+
 Navigate a browser tab:
 
 ```js
@@ -255,6 +280,21 @@ await sdk.desktopBrowser.evaluateTab("cli-browser:9555:tab:3", {
 });
 ```
 
+Preferred webpage-control pattern:
+
+```js
+const created = await sdk.desktopBrowser.createSession({
+  sessionName: "docs-research"
+});
+
+const port =
+  created?.session?.remoteDebugPort ||
+  created?.runtime?.remoteDebugPort;
+
+// Then hand off to the `agent-browser` skill using the CDP endpoint for that port,
+// e.g. http://127.0.0.1:${port}
+```
+
 ### Naming rule
 
 Prefer normal named sessions like:
@@ -457,11 +497,11 @@ Example:
 ```yaml
 tasks:
   - name: audit-fetch
-    interval: 4h
+    cron: "0 */4 * * *"
     prompt: Fetch origin/realtimex-dev and diff against tmp/frontend-audit-cursor.txt.
 
   - name: audit-ui-design
-    interval: 4h
+    cron: "15 */4 * * *"
     prompt: Review changed frontend files for UI design violations. If none, reply HEARTBEAT_OK.
 ```
 
@@ -469,7 +509,9 @@ Rules:
 - A top-level `tasks:` list means the heartbeat is split into separate scheduled tasks, not one monolithic prompt.
 - Each `- name:` item is its own task definition.
 - `name` is the stable task id. Keep it concise and stable when editing.
-- `interval` is the cadence for that specific task.
+- Use `cron` for calendar-based schedules such as hourly, daily, or weekday checks.
+- Use `interval` for duration-style repetition such as `15m`, `1h`, or `4h`.
+- If both `cron` and `interval` are present, `cron` is authoritative and `interval` is ignored.
 - `prompt` is the full instruction body for that task.
 - `HEARTBEAT_OK` means the task ran successfully but had nothing actionable to do.
 - Preserve task order unless the user explicitly wants a reordering.
@@ -479,14 +521,14 @@ When editing heartbeat files:
 - If the file already uses `tasks:`, add or edit individual task items instead of collapsing them into one large prompt.
 - If the file is a single long heartbeat prompt and the user wants separate scheduled jobs, rewrite it into a `tasks:` list with one item per independent workflow.
 - When splitting a single heartbeat into tasks, preserve the original intent, move each discrete workflow into its own `prompt`, and keep shared context text only where needed.
-- Keep YAML formatting simple: top-level `tasks:`, then `- name`, `interval`, `prompt`.
+- Keep YAML formatting simple: top-level `tasks:`, then `- name`, `cron` or `interval`, and `prompt`.
 
 When a user asks how to convert a heartbeat into task-block form, produce or edit it into this shape:
 
 ```yaml
 tasks:
   - name: task-one
-    interval: 4h
+    cron: "0 */4 * * *"
     prompt: First workflow instructions.
 
   - name: task-two

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.7.14** · 2026-05-08
+> Auto-generated from `@realtimex/sdk` source · v**1.7.16** · 2026-05-08
 
 **Package:** `@realtimex/sdk` (CJS) · **Server:** `http://localhost:3001`
 **Developer Mode auth:** `Authorization: Bearer <apiKey>`
@@ -112,11 +112,13 @@ Compatibility: `sdk.v1.desktopRuntimeSessions` remains available, but prefer the
 Use this module for the managed RealTimeX Browser control plane. This is the correct path for:
 - listing named browser sessions
 - creating a named browser session
-- opening a URL in a managed browser tab
+- opening the initial URL for a new browser session
 - reading/evaluating/focusing/navigating/closing managed browser tabs
 
 Do not use ACP for these unless the user explicitly asks for ACP browser handoff behavior.
 Do not use desktop terminal sessions for browser tabs.
+For page interaction and automation after the session is running, prefer the `agent-browser` skill against the session's CDP port.
+If the user needs a different URL, create a new browser session first instead of relying on opening another managed tab.
 
 ### `V1DesktopBrowserModule`
 
@@ -145,6 +147,10 @@ await sdk.desktopBrowser.createTab({
   url: 'https://example.com'
 });
 
+const session = await sdk.desktopBrowser.getSession('github-review');
+const port = session?.session?.remoteDebugPort || session?.runtime?.remoteDebugPort;
+// Then use the agent-browser skill against http://127.0.0.1:${port}
+
 await sdk.desktopBrowser.navigateTab('cli-browser:9555:tab:3', {
   url: 'https://docs.realtimex.ai',
   focus: true,

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

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

@@ -1146,6 +1146,11 @@ sdk.desktopBrowser.* — RealTimeX Browser sessions and tabs:
   browser-tab-close <tab-ref>
     Close a managed browser tab.
 
+  Workflow note:
+    Prefer one session per target URL. If you need another URL, create a new browser
+    session first, then use that session's remoteDebugPort with the agent-browser skill
+    over CDP for page interaction and automation.
+
   Compatibility:
     The SDK also exposes this module as sdk.v1.desktopBrowser.