@realtimex/sdk 2.0.7 → 2.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "2.0.7",
+    "version": "2.0.8",
     "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) and chat operations."
+description: "Use the RealTimeX API through the generated CLI for workspace, thread, channel (Telegram, Zalo, Discord), send messages, setup personality, and heartbeat 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.7
+   npm install -g @realtimex/pp-cli@2.0.8
    ```
 2. Verify the exact version:
    ```bash
    realtimex-pp-cli --version
    ```
-   The output must be `realtimex-pp-cli 2.0.7`.
+   The output must be `realtimex-pp-cli 2.0.8`.
 
-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.7`, 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.8`, reinstall with the pinned npm command above. Do not proceed with skill commands until exact-version verification succeeds.
 
 * Always run first:
 
@@ -70,6 +70,22 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli delete-workspace <workspaceSlug>` — Delete one workspace by exact workspace slug.
 
+**disable-plugin** — Manage disable plugin
+
+- `realtimex-pp-cli disable-plugin <pluginId>` — Disable one installed plugin globally and unload it from runtime.
+
+**disable-workspace-agent-skill** — Manage disable workspace agent skill
+
+- `realtimex-pp-cli disable-workspace-agent-skill <workspaceSlug> <skillId>` — Disable one agent skill in a workspace. Use a skill id, name, or displayName from list-workspace-agent-skills.
+
+**enable-plugin** — Manage enable plugin
+
+- `realtimex-pp-cli enable-plugin <pluginId>` — Enable one installed plugin globally and load it into runtime. Use a plugin id, name, or displayName from list-plugins.
+
+**enable-workspace-agent-skill** — Manage enable workspace agent skill
+
+- `realtimex-pp-cli enable-workspace-agent-skill <workspaceSlug> <skillId>` — Enable one agent skill in a workspace. Use a skill id, name, or displayName from list-workspace-agent-skills.
+
 **get-thread** — Manage get thread
 
 - `realtimex-pp-cli get-thread <workspaceSlug> <threadSlug>` — Get one thread by exact workspace slug and exact thread slug.
@@ -78,6 +94,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli get-workspace <workspaceSlug>` — Get one workspace by exact workspace slug.
 
+**list-agent-skills** — Manage list agent skills
+
+- `realtimex-pp-cli list-agent-skills` — List published agent skills. Use list-workspace-agent-skills to see enabled/disabled state for one workspace.
+
 **list-channels** — Manage list channels
 
 - `realtimex-pp-cli list-channels` — List configured chat channels. Use returned channel ids with update-channel.
@@ -90,10 +110,18 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli list-llm-providers` — List supported LLM providers. Use provider ids from this response when configuring workspace or thread LLM settings.
 
+**list-plugins** — Manage list plugins
+
+- `realtimex-pp-cli list-plugins` — List installed plugins with enabled state and runtime load status.
+
 **list-threads** — Manage list threads
 
 - `realtimex-pp-cli list-threads <workspaceSlug>` — List threads for one exact workspace slug.
 
+**list-workspace-agent-skills** — Manage list workspace agent skills
+
+- `realtimex-pp-cli list-workspace-agent-skills <workspaceSlug>` — List published agent skills with enabled/disabled state for one exact workspace slug.
+
 **list-workspaces** — Manage list workspaces
 
 - `realtimex-pp-cli list-workspaces` — List all workspaces visible to the current API caller. Use this before choosing a workspace slug.
@@ -102,6 +130,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli prepare` — Return compact workspace, thread, current workspace/thread from explicit workspaceSlug and threadSlug query parameters
 
+**reload-plugin** — Manage reload plugin
+
+- `realtimex-pp-cli reload-plugin <pluginId>` — Reload one enabled plugin in runtime. Disabled plugins must be enabled before reload.
+
 **rename-thread** — Manage rename thread
 
 - `realtimex-pp-cli rename-thread <workspaceSlug> <threadSlug>` — Rename one thread by exact workspace slug and exact thread slug. Only the name is changed.
@@ -114,10 +146,42 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli send-message <workspaceSlug> <threadSlug>` — Send one message to an exact thread using the same routing as channel replies.
 
+**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 main executor default terminal agent and optional model.
+
+**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 main executor 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.
+
 **set-workspace-default-agent** — Manage set workspace default agent
 
 - `realtimex-pp-cli set-workspace-default-agent <workspaceSlug>` — Set the default CLI agent for a workspace.
 
+**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.
+
+**setup-personality** — Manage setup personality
+
+- `realtimex-pp-cli setup-personality` — Set up AGENTS.md and CLAUDE.md personality files for a workspace or global ambient agent.
+
 **start-channel** — Manage start channel
 
 - `realtimex-pp-cli start-channel <channelId>` — Start one chat channel by exact channel id.
@@ -256,9 +320,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.7`, reinstall the pinned version:
+   If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.8`, reinstall the pinned version:
    ```bash
-   npm install -g @realtimex/pp-cli@2.0.7
+   npm install -g @realtimex/pp-cli@2.0.8
    ```
    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.
@@ -305,3 +369,12 @@ For workspace default-agent setup:
 * Use `prepare.agents` only.
 * Use exact agent `canonical` and optional agent `modelId` values from `prepare.agents`.
 * Never use `prepare.models` for workspace default-agent setup.
+
+For personality and heartbeat setup:
+
+* Use `setup-personality` to get the target directory for workspace or global personality files.
+* Start from `templates/AGENTS.template.md` when creating `AGENTS.md`.
+* Make `CLAUDE.md` a symlink to `AGENTS.md`.
+* Use `setup-heartbeat-tasks` to get the target `HEARTBEAT.md` path.
+* Start from `templates/HEARTBEAT.template.md` when creating `HEARTBEAT.md`.
+* Keep heartbeat instructions separate from personality files.

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

@@ -0,0 +1,49 @@
+# Agent Instructions
+
+## Mission
+
+Describe the workspace or global personality that agents should follow.
+
+You are working inside the RealTimeX app.
+
+## Role
+
+- State who the agent is for this workspace.
+- Define the agent's primary responsibility.
+- Define what the agent should avoid doing.
+
+## Boundaries
+
+- Ask for clarification when instructions are ambiguous.
+- Do not fabricate facts.
+- Do not take destructive actions without explicit approval.
+- Do not store secrets in personality files.
+
+## Tools
+
+- Describe which tools the agent may use.
+- Describe any tool-specific constraints.
+- Prefer using the `realtimex-moderator-sdk` skill for work related to RealTimeX workspaces, threads, channels (Telegram, Zalo, Discord), sending messages, setup personality, and heartbeat operations.
+- Prefer documented RealTimeX CLI commands when interacting with RealTimeX.
+
+## Memory
+
+- Record only durable preferences or facts that should affect future work.
+- Keep memory concise and verifiable.
+- Do not store credentials, tokens, or private secrets.
+
+## Style
+
+- Be concise.
+- Prefer concrete updates over speculation.
+- Explain blockers clearly.
+
+## Child Files
+
+Reference child markdown files here if used:
+
+- SOUL.md
+- USER.md
+- IDENTITY.md
+- TOOLS.md
+- MEMORY.md

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

@@ -0,0 +1,61 @@
+# Heartbeat Instructions
+
+## Mission
+
+Describe the ambient agent's standing responsibility.
+
+## Scheduled tasks (optional)
+
+Remove this section if you don't need recurring tasks.
+When present, the scheduler runs only tasks that are due on each tick.
+Tasks without an interval inherit the main check interval.
+Use `interval` for simple timing. Supported units are `m`, `h`, and `d`, for example `3m`, `1h`, or `1d`.
+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.
+
+tasks:
+
+- name: example-task
+  interval: 30m
+  agent: @codex-terminal
+  model: gpt-5.5-medium
+  skills: agent-browser, realtimex-moderator-sdk
+  prompt: Describe what the agent should do for this task
+- name: weekday-morning-task
+  cron: 0 9 * * 1-5
+  prompt: Describe what should run on a cron schedule
+- name: another-task
+  prompt: Tasks without interval run at the main 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