@realtimex/sdk 2.0.10 → 2.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "2.0.10",
+    "version": "2.0.12",
     "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,6 +1,6 @@
 ---
 name: realtimex-moderator-sdk
-description: "Use the RealTimeX API through the generated CLI for workspace, thread, channel (Telegram, Zalo, Discord), skills, plugins and send messages, setup personality, heartbeat tasks operations."
+description: "Use the RealTimeX API through the generated CLI for workspace, thread, terminal-agent sessions, channel (Telegram, Zalo, Discord), skills, plugins and send messages, setup personality, heartbeat tasks operations."
 author: ""
 license: "Apache-2.0"
 argument-hint: "<command> [args] | install cli"
@@ -20,15 +20,15 @@ This skill drives the `realtimex-pp-cli` binary. Verify the CLI is installed and
 
 1. Install or reinstall the pinned version via npm:
    ```bash
-   npm install -g @realtimex/pp-cli@2.0.10
+   npm install -g @realtimex/pp-cli@2.0.12
    ```
 2. Verify the exact version:
    ```bash
    realtimex-pp-cli --version
    ```
-   The output must be `realtimex-pp-cli 2.0.10`.
+   The output must be `realtimex-pp-cli 2.0.12`.
 
-If `--version` reports "command not found" after install, the npm global bin directory is not on `$PATH`. If it reports any version other than `2.0.10`, reinstall with the pinned npm command above. Do not proceed with skill commands until exact-version verification succeeds.
+If `--version` reports "command not found" after install, the npm global bin directory is not on `$PATH`. If it reports any version other than `2.0.12`, reinstall with the pinned npm command above. Do not proceed with skill commands until exact-version verification succeeds.
 
 * Always run first:
 
@@ -114,6 +114,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli list-plugins` — List installed plugins with enabled state and runtime load status.
 
+**list-terminal-agents** — Manage list terminal agents
+
+- `realtimex-pp-cli list-terminal-agents` — List terminal CLI agents that can be used with open-terminal-session.
+
 **list-terminal-sessions** — Manage list terminal sessions
 
 - `realtimex-pp-cli list-terminal-sessions` — List terminal runtime sessions known to the desktop app. Optionally filter by workspaceSlug and threadSlug.
@@ -130,6 +134,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli list-workspaces` — List all workspaces visible to the current API caller. Use this before choosing a workspace slug.
 
+**open-terminal-session** — Manage open terminal session
+
+- `realtimex-pp-cli open-terminal-session` — Open a new desktop terminal session for one terminal CLI agent. Use list-terminal-agents or prepare.
+
 **prepare** — Manage prepare
 
 - `realtimex-pp-cli prepare` — Return compact workspace, thread, current workspace/thread from explicit workspaceSlug and threadSlug query parameters
@@ -210,6 +218,14 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli terminate-terminal-session <sessionId>` — Terminate a terminal runtime session by detaching any controller and closing the underlying PTY session.
 
+**trigger-workspace-heartbeat** — Manage trigger workspace heartbeat
+
+- `realtimex-pp-cli trigger-workspace-heartbeat <workspaceSlug>` — Trigger the main heartbeat executor for a workspace immediately. Scheduled tasks are ignored.
+
+**trigger-workspace-heartbeat-tasks** — Manage trigger workspace heartbeat tasks
+
+- `realtimex-pp-cli trigger-workspace-heartbeat-tasks <workspaceSlug>` — Trigger specified HEARTBEAT.md task names for a workspace immediately.
+
 **update-channel** — Manage update channel
 
 - `realtimex-pp-cli update-channel <channelId>` — Update one chat channel by exact channel id. Only channel writable fields are changed.
@@ -340,9 +356,9 @@ Verify: `claude mcp list`
    ```bash
    realtimex-pp-cli --version
    ```
-   If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.10`, reinstall the pinned version:
+   If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.12`, reinstall the pinned version:
    ```bash
-   npm install -g @realtimex/pp-cli@2.0.10
+   npm install -g @realtimex/pp-cli@2.0.12
    ```
    Then run `realtimex-pp-cli --version` again and proceed only after exact-version verification succeeds.
 2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
@@ -399,6 +415,15 @@ For workspace default-agent setup:
 * Use exact agent `canonical` and optional agent `modelId` values from `prepare.agents`.
 * Never use `prepare.models` for workspace default-agent setup.
 
+For terminal agents and terminal sessions:
+
+* Use `list-terminal-agents` when you only need available terminal agents. Use `prepare` when you also need workspace/thread/provider/model context.
+* Use `open-terminal-session` to open a new desktop terminal session for a terminal agent. It auto-attaches the CLI controller through the desktop runtime launch request.
+* Use exact `agentName`, `providerId`, and `modelId` values from `list-terminal-agents` or `prepare.agents`.
+* When opening a terminal session for the current thread, pass both `--workspace-slug "$RTX_WORKSPACE_SLUG"` and `--thread-slug "$RTX_THREAD_SLUG"`.
+* Use `list-terminal-sessions` to inspect grouped terminal sessions by `workspaceSlug` and `threadSlug`. Each session includes compact identity fields and `attached` status.
+* Use `resume-terminal-session` or `resume-latest-terminal-session` to resume + attach an existing session. Use `terminate-terminal-session` to close + detach a session.
+
 For agent skills:
 
 * Use `list-workspace-agent-skills` before enabling, disabling, or reloading workspace skills.

package/skills/realtimex-moderator-sdk/templates/HEARTBEAT.template.md

@@ -14,7 +14,32 @@ Use `cron` for complex schedules, for example `0 9 * * *`.
 Use `agent` to run a task with a specific terminal agent, for example `@codex-terminal`.
 Use `model` to run a task with a specific model, for example `gpt-5.5-medium`.
 Use `skills` to prefer skills for the task, for example `agent-browser, realtimex-moderator-sdk`.
-`agent`, `model`, `skills`, `interval`, and `cron` are optional. If omitted, the task inherits from the main heartbeat executor.
+Use `executor: shell` and `command` to run a shell command instead of an agent.
+`agent`, `model`, `skills`, `executor`, `command`, `interval`, and `cron` are optional. If omitted, the task inherits from the main heartbeat executor.
+When a shell command prints valid JSON, it can trigger additional tasks. Use one of these forms:
+
+```json
+["task-name-1", "task-name-2"]
+```
+
+```json
+{
+  "tasks": ["task-name-1", "task-name-2"],
+  "reason": "metrics changed"
+}
+```
+
+To trigger tasks in another workspace, include `workspace`:
+
+```json
+{
+  "workspace": "other-workspace-slug",
+  "tasks": ["task-name-1"],
+  "reason": "shared dependency changed"
+}
+```
+
+Only valid JSON triggers task dispatch. If the shell output is not valid JSON, no extra tasks are run.
 
 tasks:
 
@@ -27,6 +52,10 @@ tasks:
 - name: weekday-morning-task
   cron: 0 9 * * 1-5
   prompt: Describe what should run on a cron schedule
+- name: sync-metrics
+  interval: 30m
+  executor: shell
+  command: bash ./scripts/sync-metrics.sh
 - name: another-task
   prompt: Tasks without interval run at the main check interval