@realtimex/sdk 2.0.33 → 2.0.34

package/README.md

@@ -74,5 +74,8 @@ server-error retries reuse the serialized body, timestamp, and delivery ID so
 the receiving endpoint can deduplicate delivery safely. A successful receipt
 confirms acceptance and routing, not agent-task completion.
 
-The package also publishes generated skill assets under
-`skills/realtimex-moderator-sdk`.
+The package publishes a concise router at `skills/realtimex-moderator-sdk` and
+focused generated skills for workspaces, terminal agents, browser sessions,
+Local Apps, heartbeat, automation flows, artifacts, channels, webhooks, and
+plugin/skill administration. All skills use the same pinned
+`realtimex-pp-cli` binary.

package/index.js

@@ -2150,5 +2150,5 @@ module.exports = {
   createRealtimeXClient,
   createRealtimeXWebhookClient,
   operations,
-  version: "2.0.33",
+  version: "2.0.34",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "2.0.33",
+    "version": "2.0.34",
     "description": "RealtimeX runtime SDK package and moderator agent skill assets.",
     "private": false,
     "main": "./index.js",

package/skills/realtimex-artifacts/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: realtimex-artifacts
+description: "List, publish, inspect, pause, resume, and revoke RealTimeX workspace artifacts. Use for browser-viewable artifact publication and lifecycle management."
+allowed-tools: "Read Bash"
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - realtimex-pp-cli
+---
+
+# RealTimeX Artifacts
+
+List, publish, inspect, pause, resume, and revoke RealTimeX workspace artifacts. Use for browser-viewable artifact publication and lifecycle management.
+
+## CLI setup
+
+This skill uses `realtimex-pp-cli` version 2.0.34. Before using its commands:
+
+```bash
+realtimex-pp-cli --version
+```
+
+If it is missing or does not report `realtimex-pp-cli 2.0.34`, install the pinned version:
+
+```bash
+npm install -g @realtimex/pp-cli@2.0.34
+```
+
+For requests about the current workspace or thread, resolve context first:
+
+```bash
+realtimex-pp-cli prepare --agent
+```
+
+## Command reference
+
+**get-artifact** — Manage get artifact
+
+- `realtimex-pp-cli get-artifact <artifactId>` — Get one public artifact by artifact id.
+
+**list-artifacts** — Manage list artifacts
+
+- `realtimex-pp-cli list-artifacts <workspaceSlug>` — List public artifacts for one exact workspace slug. Revoked artifacts are hidden unless includeRevoked=true is passed.
+
+**pause-artifact** — Manage pause artifact
+
+- `realtimex-pp-cli pause-artifact <artifactId>` — Pause one published artifact by artifact id. Paused artifacts remain listed but stop serving publicly.
+
+**publish-artifact** — Manage publish artifact
+
+- `realtimex-pp-cli publish-artifact <workspaceSlug>` — Publish a browser-viewable file or folder under a workspace artifacts directory.
+
+**resume-artifact** — Manage resume artifact
+
+- `realtimex-pp-cli resume-artifact <artifactId>` — Resume one paused artifact by artifact id.
+
+**revoke-artifact** — Manage revoke artifact
+
+- `realtimex-pp-cli revoke-artifact <artifactId>` — Revoke one artifact by artifact id.
+
+## Domain rules
+
+- Place publishable files or folders under the workspace `artifacts/` directory before publishing.
+- Use the exact artifact identifier returned by list or publish operations for lifecycle changes.
+- Treat revoke as the permanent serving-state action and require an explicit target.
+
+## Shared constraints
+
+- Run documented commands with `--agent`.
+- Use exact identifiers returned by `prepare` or the relevant list/get command; do not guess values.
+- Do not bypass the CLI with raw HTTP calls. If a required operation is absent, report that limitation.
+- Ask one concise clarification when required target context is missing or ambiguous.

package/skills/realtimex-automation-flows/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: realtimex-automation-flows
+description: "Run RealTimeX automation workflows and guided automation-flow commands, including working-directory setup and workspace layout. Use for explicit multi-step automation execution."
+allowed-tools: "Read Bash"
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - realtimex-pp-cli
+---
+
+# RealTimeX Automation Flows
+
+Run RealTimeX automation workflows and guided automation-flow commands, including working-directory setup and workspace layout. Use for explicit multi-step automation execution.
+
+## CLI setup
+
+This skill uses `realtimex-pp-cli` version 2.0.34. Before using its commands:
+
+```bash
+realtimex-pp-cli --version
+```
+
+If it is missing or does not report `realtimex-pp-cli 2.0.34`, install the pinned version:
+
+```bash
+npm install -g @realtimex/pp-cli@2.0.34
+```
+
+For requests about the current workspace or thread, resolve context first:
+
+```bash
+realtimex-pp-cli prepare --agent
+```
+
+## Command reference
+
+**chat-with-terminal-agent** — Manage chat with terminal agent
+
+- `realtimex-pp-cli chat-with-terminal-agent` — Guide a user through sending a chat message to the terminal agent.
+
+**goal-kickoff-composer** — Manage goal kickoff composer
+
+- `realtimex-pp-cli goal-kickoff-composer` — Verify the shared Project/global Goal kickoff composer, routing, attachment authorization, retry, preview
+
+**run-automation-workflow** — Manage run automation workflow
+
+- `realtimex-pp-cli run-automation-workflow` — Run any app automation flow or scenario exposed via flowMetadata.cli.enabled=true by passing workflowName.
+
+**set-default-workspace-agent** — Manage set default workspace agent
+
+- `realtimex-pp-cli set-default-workspace-agent` — Set a workspace default agent from the desktop workspace chat settings UI.
+
+**setup-working-dir** — Manage setup working dir
+
+- `realtimex-pp-cli setup-working-dir` — Add or edit an agent working directory from the desktop settings UI.
+
+**workspace-shell-layout** — Manage workspace shell layout
+
+- `realtimex-pp-cli workspace-shell-layout` — Verify workspace navigation, title-bar containment, Files dock behavior
+
+## Domain rules
+
+- Do not automatically retry workflow timeouts or server errors; report the failure so the user can decide.
+- Resolve current workspace and thread context before running a flow that depends on them.
+- Use the explicit generated flow command when one exists; use the generic workflow command only for supported workflow input.
+
+## Shared constraints
+
+- Run documented commands with `--agent`.
+- Use exact identifiers returned by `prepare` or the relevant list/get command; do not guess values.
+- Do not bypass the CLI with raw HTTP calls. If a required operation is absent, report that limitation.
+- Ask one concise clarification when required target context is missing or ambiguous.

package/skills/realtimex-browser-sessions/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: realtimex-browser-sessions
+description: "List, create, start, stop, and delete isolated RealTimeX browser sessions. Use for named browser runtime and profile lifecycle work."
+allowed-tools: "Read Bash"
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - realtimex-pp-cli
+---
+
+# RealTimeX Browser Sessions
+
+List, create, start, stop, and delete isolated RealTimeX browser sessions. Use for named browser runtime and profile lifecycle work.
+
+## CLI setup
+
+This skill uses `realtimex-pp-cli` version 2.0.34. Before using its commands:
+
+```bash
+realtimex-pp-cli --version
+```
+
+If it is missing or does not report `realtimex-pp-cli 2.0.34`, install the pinned version:
+
+```bash
+npm install -g @realtimex/pp-cli@2.0.34
+```
+
+For requests about the current workspace or thread, resolve context first:
+
+```bash
+realtimex-pp-cli prepare --agent
+```
+
+## Command reference
+
+**create-browser-session** — Manage create browser session
+
+- `realtimex-pp-cli create-browser-session` — Create an isolated named RealTimeX Browser session. When url is supplied, start the session and open that URL.
+
+**delete-browser-session** — Manage delete browser session
+
+- `realtimex-pp-cli delete-browser-session <sessionName>` — Delete a stopped named RealTimeX Browser session and its isolated profile.
+
+**list-browser-sessions** — Manage list browser sessions
+
+- `realtimex-pp-cli list-browser-sessions` — List registered RealTimeX Browser sessions and their live runtime state.
+
+**start-browser-session** — Manage start browser session
+
+- `realtimex-pp-cli start-browser-session <sessionName>` — Start an existing named RealTimeX Browser session, optionally opening an absolute HTTP or HTTPS URL.
+
+**stop-browser-session** — Manage stop browser session
+
+- `realtimex-pp-cli stop-browser-session <sessionName>` — Gracefully stop an existing named RealTimeX Browser session.
+
+## Domain rules
+
+- List browser sessions before lifecycle changes and use the exact returned session name.
+- Create a named session before starting it; stop it before permanent deletion.
+- Treat each named browser session as an isolated profile and do not substitute terminal-session identifiers.
+
+## Shared constraints
+
+- Run documented commands with `--agent`.
+- Use exact identifiers returned by `prepare` or the relevant list/get command; do not guess values.
+- Do not bypass the CLI with raw HTTP calls. If a required operation is absent, report that limitation.
+- Ask one concise clarification when required target context is missing or ambiguous.

package/skills/realtimex-channels/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: realtimex-channels
+description: "Create, configure, start, stop, and delete RealTimeX chat channels, approve pairing codes, and deliver channel files. Use for Telegram, Zalo, Discord, and other channel integrations."
+allowed-tools: "Read Bash"
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - realtimex-pp-cli
+---
+
+# RealTimeX Channels
+
+Create, configure, start, stop, and delete RealTimeX chat channels, approve pairing codes, and deliver channel files. Use for Telegram, Zalo, Discord, and other channel integrations.
+
+## CLI setup
+
+This skill uses `realtimex-pp-cli` version 2.0.34. Before using its commands:
+
+```bash
+realtimex-pp-cli --version
+```
+
+If it is missing or does not report `realtimex-pp-cli 2.0.34`, install the pinned version:
+
+```bash
+npm install -g @realtimex/pp-cli@2.0.34
+```
+
+For requests about the current workspace or thread, resolve context first:
+
+```bash
+realtimex-pp-cli prepare --agent
+```
+
+## Command reference
+
+**approve-channel-pairing-code** — Manage approve channel pairing code
+
+- `realtimex-pp-cli approve-channel-pairing-code <code>` — Approve one pending channel pairing code by visible 6-digit code or database id.
+
+**create-channel** — Manage create channel
+
+- `realtimex-pp-cli create-channel <workspaceSlug>` — Create a chat channel in one exact workspace. Defaults to Telegram when plugin_type, channelType, and type are omitted.
+
+**delete-channel** — Manage delete channel
+
+- `realtimex-pp-cli delete-channel <channelId>` — Delete one chat channel by exact channel id.
+
+**list-channels** — Manage list channels
+
+- `realtimex-pp-cli list-channels` — List configured chat channels. Use returned channel ids with update-channel.
+
+**send-channel-file** — Manage send channel file
+
+- `realtimex-pp-cli send-channel-file` — Send one local CLI file back to an external channel using an explicit channel delivery context id.
+
+**start-channel** — Manage start channel
+
+- `realtimex-pp-cli start-channel <channelId>` — Start one chat channel by exact channel id.
+
+**stop-channel** — Manage stop channel
+
+- `realtimex-pp-cli stop-channel <channelId>` — Stop one chat channel by exact channel id.
+
+**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.
+
+## Domain rules
+
+- List channels before changing them and use the exact channel identifier returned by the server.
+- Use an explicit channel delivery context when sending a file, and send one file per command.
+- Approve only the pairing code explicitly presented by the user or current channel flow.
+
+## Shared constraints
+
+- Run documented commands with `--agent`.
+- Use exact identifiers returned by `prepare` or the relevant list/get command; do not guess values.
+- Do not bypass the CLI with raw HTTP calls. If a required operation is absent, report that limitation.
+- Ask one concise clarification when required target context is missing or ambiguous.

package/skills/realtimex-heartbeat/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: realtimex-heartbeat
+description: "Configure RealTimeX heartbeat scheduling, agents, active hours, timezone, autopilot, and immediate workspace heartbeat runs. Use for recurring HEARTBEAT.md task execution."
+allowed-tools: "Read Bash"
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - realtimex-pp-cli
+---
+
+# RealTimeX Heartbeat
+
+Configure RealTimeX heartbeat scheduling, agents, active hours, timezone, autopilot, and immediate workspace heartbeat runs. Use for recurring HEARTBEAT.md task execution.
+
+## CLI setup
+
+This skill uses `realtimex-pp-cli` version 2.0.34. Before using its commands:
+
+```bash
+realtimex-pp-cli --version
+```
+
+If it is missing or does not report `realtimex-pp-cli 2.0.34`, install the pinned version:
+
+```bash
+npm install -g @realtimex/pp-cli@2.0.34
+```
+
+For requests about the current workspace or thread, resolve context first:
+
+```bash
+realtimex-pp-cli prepare --agent
+```
+
+## Command reference
+
+**set-heartbeat-active-hours** — Manage set heartbeat active hours
+
+- `realtimex-pp-cli set-heartbeat-active-hours` — Set workspace or global ambient-agent active hours using HH:mm start and end values.
+
+**set-heartbeat-auto-pilot** — Manage set heartbeat auto pilot
+
+- `realtimex-pp-cli set-heartbeat-auto-pilot` — Turn workspace or global ambient-agent heartbeat auto pilot on or off.
+
+**set-heartbeat-default-agent** — Manage set heartbeat default agent
+
+- `realtimex-pp-cli set-heartbeat-default-agent` — Set workspace or global ambient-agent default terminal agent and optional model for heartbeat defaults and legacy
+
+**set-heartbeat-enabled** — Manage set heartbeat enabled
+
+- `realtimex-pp-cli set-heartbeat-enabled` — Turn workspace or global ambient-agent heartbeat on or off.
+
+**set-heartbeat-interval** — Manage set heartbeat interval
+
+- `realtimex-pp-cli set-heartbeat-interval` — Set workspace or global ambient-agent scheduler check interval.
+
+**set-heartbeat-timezone** — Manage set heartbeat timezone
+
+- `realtimex-pp-cli set-heartbeat-timezone` — Set workspace or global ambient-agent heartbeat timezone, for example Asia/Saigon or UTC.
+
+**setup-heartbeat-tasks** — Manage setup heartbeat tasks
+
+- `realtimex-pp-cli setup-heartbeat-tasks` — Set up HEARTBEAT.md task instructions for a workspace or global ambient agent.
+
+**trigger-workspace-heartbeat** — Manage trigger workspace heartbeat
+
+- `realtimex-pp-cli trigger-workspace-heartbeat <workspaceSlug>` — Trigger the default HEARTBEAT.md task for a workspace immediately.
+
+**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.
+
+## Domain rules
+
+- Keep heartbeat instructions in `HEARTBEAT.md`; use the bundled template when creating it.
+- Inspect the current workspace context before changing heartbeat configuration or triggering tasks.
+- Use exact task names from `HEARTBEAT.md` when triggering selected heartbeat tasks.
+
+## Shared constraints
+
+- Run documented commands with `--agent`.
+- Use exact identifiers returned by `prepare` or the relevant list/get command; do not guess values.
+- Do not bypass the CLI with raw HTTP calls. If a required operation is absent, report that limitation.
+- Ask one concise clarification when required target context is missing or ambiguous.

package/skills/realtimex-heartbeat/templates/HEARTBEAT.template.md

@@ -0,0 +1,99 @@
+# Heartbeat Instructions
+
+## Mission
+
+Describe the ambient agent's standing responsibility.
+
+## Tasks
+
+The scheduler evaluates this `tasks:` block on every heartbeat tick and runs only tasks that are due.
+The first task is treated as the default task unless another task has `default: true`.
+Use `default: true` on exactly one task to make it the default manual heartbeat target.
+Use `default: false` on the first task if you do not want any task to be auto-selected as default.
+Use `interval` for simple timing. Supported units are `m`, `h`, and `d`, for example `3m`, `1h`, or `1d`.
+Omit `interval` and `cron` to run on every scheduler check interval.
+Use `interval: disabled` to keep a task in the file but skip it during scheduled heartbeat checks. Manual triggers can still run the task.
+Use `cron` for complex schedules, for example `0 9 * * *`.
+Agent tasks require `agent`, for example `@codex`.
+Use `model` to run an agent task with a specific model, for example `gpt-5.5-medium`.
+Use `skills` to prefer skills for an agent task, for example `agent-browser, realtimex-moderator-sdk`.
+Use `executor: shell` and `command` to run a shell command instead of an agent. Shell tasks do not use `prompt`.
+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:
+
+- name: default-review
+  default: true
+  interval: 30m
+  agent: @codex
+  model: gpt-5.5-medium
+  skills: agent-browser, realtimex-moderator-sdk
+  prompt: Review the workspace context and respond HEARTBEAT_OK when no action is needed
+- name: weekday-morning-task
+  cron: 0 9 * * 1-5
+  agent: @codex
+  prompt: Describe what should run on a cron schedule
+- name: sync-metrics
+  interval: 30m
+  executor: shell
+  command: bash ./scripts/sync-metrics.sh
+- name: paused-task
+  interval: disabled
+  agent: @codex
+  prompt: This task is skipped by scheduled heartbeat checks until re-enabled
+- name: another-task
+  agent: @codex
+  prompt: Tasks without interval or cron run on every scheduler check interval
+
+## Check for
+
+- Pending tasks that require follow-up
+- New events that need awareness
+
+## When action is needed
+
+- State what should trigger action
+- Describe the preferred next step
+- If calendar routine context is provided, use it only when a concise update would help
+
+## When nothing is needed
+
+- Reply exactly HEARTBEAT_OK
+
+## Allowed actions
+
+- Review the current workspace context
+- Create or update relevant artifacts when necessary
+
+## Never do
+
+- Do not repeat old work without a clear reason
+- Do not take destructive actions without explicit approval
+
+## Style
+
+- Be concise
+- Prefer concrete updates over speculation

package/skills/realtimex-local-apps/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: realtimex-local-apps
+description: "Create, inspect, configure, start, stop, restart, and delete RealTimeX Local Apps. Use for local source, npx, uvx, webhook-trigger, status, log, and lifecycle operations."
+allowed-tools: "Read Bash"
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - realtimex-pp-cli
+---
+
+# RealTimeX Local Apps
+
+Create, inspect, configure, start, stop, restart, and delete RealTimeX Local Apps. Use for local source, npx, uvx, webhook-trigger, status, log, and lifecycle operations.
+
+## CLI setup
+
+This skill uses `realtimex-pp-cli` version 2.0.34. Before using its commands:
+
+```bash
+realtimex-pp-cli --version
+```
+
+If it is missing or does not report `realtimex-pp-cli 2.0.34`, install the pinned version:
+
+```bash
+npm install -g @realtimex/pp-cli@2.0.34
+```
+
+For requests about the current workspace or thread, resolve context first:
+
+```bash
+realtimex-pp-cli prepare --agent
+```
+
+## Command reference
+
+**create-local-app** — Manage create local app
+
+- `realtimex-pp-cli create-local-app` — Create local app
+
+**delete-local-app** — Manage delete local app
+
+- `realtimex-pp-cli delete-local-app <appId>` — Delete local app
+
+**get-local-app** — Manage get local app
+
+- `realtimex-pp-cli get-local-app <appId>` — Get local app
+
+**get-local-app-logs** — Manage get local app logs
+
+- `realtimex-pp-cli get-local-app-logs <appId>` — Read bounded recent desktop logs. Each entry is capped at 4 KiB and secret-bearing configuration is omitted.
+
+**get-local-app-status** — Manage get local app status
+
+- `realtimex-pp-cli get-local-app-status <appId>` — Get local app status
+
+**list-local-apps** — Manage list local apps
+
+- `realtimex-pp-cli list-local-apps` — List local apps
+
+**restart-local-app** — Manage restart local app
+
+- `realtimex-pp-cli restart-local-app <appId>` — Restart local app
+
+**set-local-app-enabled** — Manage set local app enabled
+
+- `realtimex-pp-cli set-local-app-enabled <appId>` — Set local app enabled
+
+**start-local-app** — Manage start local app
+
+- `realtimex-pp-cli start-local-app <appId>` — Start local app
+
+**stop-local-app** — Manage stop local app
+
+- `realtimex-pp-cli stop-local-app <appId>` — Stop local app
+
+**update-local-app** — Manage update local app
+
+- `realtimex-pp-cli update-local-app <appId>` — Update local app
+
+## Domain rules
+
+- List or inspect an app before changing lifecycle or configuration state, and use the exact app identifier returned by the server.
+- Treat endpoint association and runtime state as server-owned values; confirm status after start, stop, or restart.
+- Use bounded log reads for diagnosis and require explicit user intent before permanent app deletion.
+
+## Shared constraints
+
+- Run documented commands with `--agent`.
+- Use exact identifiers returned by `prepare` or the relevant list/get command; do not guess values.
+- Do not bypass the CLI with raw HTTP calls. If a required operation is absent, report that limitation.
+- Ask one concise clarification when required target context is missing or ambiguous.