@realtimex/sdk 2.0.4 → 2.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "2.0.4",
+    "version": "2.0.5",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -25,6 +25,7 @@
         "sdk:generate:force": "node ../scripts/generate-v1-sdk.mjs --force",
         "sdk:diff": "node ../scripts/generate-v1-sdk.mjs --dry-run",
         "skill:generate": "node ../scripts/generate-skill.mjs --force",
+        "skill:local-test": "node ../scripts/local-test-realtimex-skill.mjs",
         "pp-cli:build": "node ../scripts/build-pp-cli-packages.mjs",
         "pp-cli:publish": "node ../scripts/publish-pp-cli-packages.mjs",
         "prepublishOnly": "npm run build && npm run skill:generate"

package/skills/realtimex-moderator-sdk/SKILL.md

@@ -16,177 +16,85 @@ metadata:
 
 ## Prerequisites: Install the CLI
 
-This skill drives the `realtimex-pp-cli` binary. Verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
+This skill drives the `realtimex-pp-cli` binary. Verify the CLI is installed and exactly matches this skill's SDK version before invoking any command from this skill. If it is missing or the version does not match, reinstall the pinned version first:
 
-1. Install via npm:
+1. Install or reinstall the pinned version via npm:
    ```bash
-   npm install -g @realtimex/pp-cli@2.0.4
+   npm install -g @realtimex/pp-cli@2.0.5
    ```
-2. Verify: `realtimex-pp-cli --version`
+2. Verify the exact version:
+   ```bash
+   realtimex-pp-cli --version
+   ```
+   The output must be `realtimex-pp-cli 2.0.5`.
 
-If `--version` reports "command not found" after install, the npm global bin directory is not on `$PATH`. Do not proceed with skill commands until 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.5`, reinstall with the pinned npm command above. Do not proceed with skill commands until exact-version verification succeeds.
 
 ## Command Reference
 
-**chat-feedback** — Manage chat feedback
-
-- `realtimex-pp-cli chat-feedback <slug> <chatId>` — Update workspace chat feedback.
-
-**chats** — Manage chats
-
-- `realtimex-pp-cli chats <slug>` — Get workspace chats.
-
-**config** — Manage config
-
-- `realtimex-pp-cli config get-workspace` — Get or create workspace config.
-- `realtimex-pp-cli config update-workspace` — Update workspace config.
-
-**delete-chats** — Manage delete chats
-
-- `realtimex-pp-cli delete-chats <slug>` — Delete selected workspace chats.
-
-**delete-edited-chats** — Manage delete edited chats
-
-- `realtimex-pp-cli delete-edited-chats <slug>` — Delete edited workspace chats from a starting id.
-
-**document** — Manage document
-
-- `realtimex-pp-cli document <slug> <docPath>` — Get document content for a workspace document.
-
-**linked-terminal-message** — Manage linked terminal message
-
-- `realtimex-pp-cli linked-terminal-message <slug>` — Persist a linked terminal message.
-
-**llm-provider** — Manage llm provider
-
-- `realtimex-pp-cli llm-provider <slug>` — Get workspace LLM provider metadata.
-
-**local-llm-tuning-suggestion** — Manage local llm tuning suggestion
-
-- `realtimex-pp-cli local-llm-tuning-suggestion <slug>` — Generate a local LLM tuning suggestion.
-
-**pfp** — Manage pfp
-
-- `realtimex-pp-cli pfp <slug>` — Get a workspace profile picture.
-
-**prompt-history** — Manage prompt history
-
-- `realtimex-pp-cli prompt-history delete-workspace` — Clear workspace prompt history.
-- `realtimex-pp-cli prompt-history delete-workspace-entry` — Delete a workspace prompt history entry.
-- `realtimex-pp-cli prompt-history get-workspace` — Get workspace prompt history.
-
-**realtimex-developer-search** — Manage realtimex developer search
-
-- `realtimex-pp-cli realtimex-developer-search <slug>` — Validate search provider configuration.
-
-**remove-and-unembed** — Manage remove and unembed
+**clear-workspace-default-agent** — Manage clear workspace default agent
 
-- `realtimex-pp-cli remove-and-unembed <slug>` — Remove and unembed a document.
+- `realtimex-pp-cli clear-workspace-default-agent <workspaceSlug>` — Clear the default CLI agent from a workspace.
 
-**remove-pfp** — Manage remove pfp
+**create-thread** — Manage create thread
 
-- `realtimex-pp-cli remove-pfp <slug>` — Remove a workspace profile picture.
+- `realtimex-pp-cli create-thread <workspaceSlug>` — Create a thread in one workspace. The name is optional but recommended.
 
-**reset-vector-db** — Manage reset vector db
+**create-workspace** — Manage create workspace
 
-- `realtimex-pp-cli reset-vector-db <slug>` — Reset workspace vector database records.
+- `realtimex-pp-cli create-workspace` — Create a workspace. Requires a human-readable workspace name.
 
-**stream-chat** — Manage stream chat
+**delete-thread** — Manage delete thread
 
-- `realtimex-pp-cli stream-chat <slug>` — Stream a chat response for a workspace default thread.
+- `realtimex-pp-cli delete-thread <workspaceSlug> <threadSlug>` — Delete one thread by exact workspace slug and exact thread slug.
 
-**suggested-messages** — Manage suggested messages
+**delete-workspace** — Manage delete workspace
 
-- `realtimex-pp-cli suggested-messages get-workspace` — Get suggested messages for a workspace.
-- `realtimex-pp-cli suggested-messages save-workspace` — Save suggested messages for a workspace.
+- `realtimex-pp-cli delete-workspace <workspaceSlug>` — Delete one workspace by exact workspace slug.
 
-**terminal-goal** — Manage terminal goal
+**get-thread** — Manage get thread
 
-- `realtimex-pp-cli terminal-goal <slug>` — Create a terminal goal for a workspace.
+- `realtimex-pp-cli get-thread <workspaceSlug> <threadSlug>` — Get one thread by exact workspace slug and exact thread slug.
 
-**terminal-goal-draft** — Manage terminal goal draft
+**get-workspace** — Manage get workspace
 
-- `realtimex-pp-cli terminal-goal-draft <slug>` — Draft a terminal goal for a workspace.
+- `realtimex-pp-cli get-workspace <workspaceSlug>` — Get one workspace by exact workspace slug.
 
-**terminal-session-details** — Manage terminal session details
+**list-llm-models** — Manage list llm models
 
-- `realtimex-pp-cli terminal-session-details <slug>` — Get workspace terminal session details.
+- `realtimex-pp-cli list-llm-models <provider>` — List models for one provider id. Use an exact model id from this response with send-llm-message.
 
-**terminal-ui-events** — Manage terminal ui events
+**list-llm-providers** — Manage list llm providers
 
-- `realtimex-pp-cli terminal-ui-events <slug>` — Persist terminal UI events.
+- `realtimex-pp-cli list-llm-providers` — List supported LLM providers. Use provider ids from this response with list-llm-models and send-llm-message.
 
-**thread** — Manage thread
+**list-threads** — Manage list threads
 
-- `realtimex-pp-cli thread coordinate-task` — Coordinate a task into a workspace thread.
-- `realtimex-pp-cli thread create` — Create a workspace thread.
-- `realtimex-pp-cli thread delete` — Delete a workspace thread.
-- `realtimex-pp-cli thread fork` — Fork the workspace default thread.
-- `realtimex-pp-cli thread get` — Get a workspace thread.
+- `realtimex-pp-cli list-threads <workspaceSlug>` — List threads for one exact workspace slug.
 
-**thread-bulk-delete** — Manage thread bulk delete
+**list-workspaces** — Manage list workspaces
 
-- `realtimex-pp-cli thread-bulk-delete <slug>` — Bulk delete workspace threads.
+- `realtimex-pp-cli list-workspaces` — List all workspaces visible to the current API caller. Use this before choosing a workspace slug.
 
-**thread-events** — Manage thread events
+**prepare** — Manage prepare
 
-- `realtimex-pp-cli thread-events <slug>` — Open an SSE stream for workspace thread events.
+- `realtimex-pp-cli prepare` — Return compact workspace, thread, LLM provider, model, and CLI agent context for agents before choosing arguments.
 
-**threads** — Manage threads
+**rename-thread** — Manage rename thread
 
-- `realtimex-pp-cli threads <slug>` — List workspace threads.
+- `realtimex-pp-cli rename-thread <workspaceSlug> <threadSlug>` — Rename one thread by exact workspace slug and exact thread slug. Only the name is changed.
 
-**tts** — Manage tts
+**rename-workspace** — Manage rename workspace
 
-- `realtimex-pp-cli tts <slug> <chatId>` — Generate text-to-speech audio for a workspace chat.
+- `realtimex-pp-cli rename-workspace <workspaceSlug>` — Rename one workspace by exact workspace slug. Only the name is changed.
 
-**update** — Manage update
+**send-llm-message** — Manage send llm message
 
-- `realtimex-pp-cli update <slug>` — Update workspace settings by slug.
+- `realtimex-pp-cli send-llm-message <workspaceSlug> <threadSlug>` — Send one non-streaming LLM message to an exact thread.
 
-**update-chat** — Manage update chat
+**set-workspace-default-agent** — Manage set workspace default agent
 
-- `realtimex-pp-cli update-chat <slug>` — Update a workspace chat response.
-
-**update-embeddings** — Manage update embeddings
-
-- `realtimex-pp-cli update-embeddings <slug>` — Update workspace document embeddings.
-
-**update-pin** — Manage update pin
-
-- `realtimex-pp-cli update-pin <slug>` — Update workspace document pin status.
-
-**upload** — Manage upload
-
-- `realtimex-pp-cli upload <slug>` — Upload a document to workspace documents.
-
-**upload-and-embed** — Manage upload and embed
-
-- `realtimex-pp-cli upload-and-embed <slug>` — Upload and embed a document.
-
-**upload-link** — Manage upload link
-
-- `realtimex-pp-cli upload-link <slug>` — Upload a link to workspace documents.
-
-**upload-pfp** — Manage upload pfp
-
-- `realtimex-pp-cli upload-pfp <slug>` — Upload a workspace profile picture.
-
-**vision-availability** — Manage vision availability
-
-- `realtimex-pp-cli vision-availability <slug>` — Get workspace vision availability.
-
-**workspace** — Manage workspace
-
-- `realtimex-pp-cli workspace create` — Create a workspace using the app workspace creation behavior.
-- `realtimex-pp-cli workspace delete` — Delete a workspace.
-- `realtimex-pp-cli workspace get` — Get a workspace by slug.
-- `realtimex-pp-cli workspace hide-chat` — Hide a workspace chat.
-- `realtimex-pp-cli workspace search` — Search workspaces and threads.
-
-**workspaces** — Manage workspaces
-
-- `realtimex-pp-cli workspaces` — List workspaces using the app workspace list behavior.
+- `realtimex-pp-cli set-workspace-default-agent <workspaceSlug>` — Set the default CLI agent for a workspace.
 
 
 ### Finding the right command
@@ -218,7 +126,7 @@ Add `--agent` to any command. Expands to: `--json --compact --no-input --no-colo
 - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
 
   ```bash
-  realtimex-pp-cli thread get mock-value mock-value --agent --select id,name,status
+  realtimex-pp-cli clear-workspace-default-agent mock-value --agent --select id,name,status
   ```
 - **Previewable** — `--dry-run` shows the request without sending
 - **Offline-friendly** — sync/search commands can use the local SQLite store when available
@@ -270,7 +178,7 @@ A profile is a saved set of flag values, reused across invocations. Use it when
 
 ```
 realtimex-pp-cli profile save briefing --json
-realtimex-pp-cli --profile briefing thread get mock-value mock-value
+realtimex-pp-cli --profile briefing clear-workspace-default-agent mock-value
 realtimex-pp-cli profile list --json
 realtimex-pp-cli profile show briefing
 realtimex-pp-cli profile delete briefing --yes
@@ -310,8 +218,15 @@ Verify: `claude mcp list`
 
 ## Direct Use
 
-1. Check if installed: `which realtimex-pp-cli`
-   If not found, offer to install (see Prerequisites at the top of this skill).
+1. Check whether the CLI is installed and version-matched:
+   ```bash
+   realtimex-pp-cli --version
+   ```
+   If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.5`, reinstall the pinned version:
+   ```bash
+   npm install -g @realtimex/pp-cli@2.0.5
+   ```
+   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.
 3. Execute with the `--agent` flag:
    ```bash
@@ -321,6 +236,46 @@ Verify: `claude mcp list`
 
 ## Constraints
 
-Use only the `realtimex-pp-cli` commands documented by this skill. Never call the RealTimeX API directly with `curl`, `fetch`, raw HTTP clients, or custom scripts.
+This skill intentionally exposes a small action-first command set. Prefer these generated commands over older nested resource commands.
+
+* Use only documented `realtimex-pp-cli` commands.
+* Never call the RealTimeX API directly with `curl`, `fetch`, raw HTTP clients, or custom scripts.
+* If the current CLI cannot do the requested task, say the feature is not available and will be added soon.
+* Use `--agent` on every command.
+* Always run first:
+
+  ```bash
+  realtimex-pp-cli prepare --agent
+  ```
 
-If a requested task is impossible with the current CLI commands, do not work around it through direct API calls or undocumented behavior. Say the feature is not available and will be added soon.
+* Use exact workspace slugs, thread slugs, provider ids, model ids, agent `canonical`, and agent `modelId` values from `prepare`.
+* Do not guess workspace, thread, model, provider, agent, message, target, or option values.
+* If required context is missing or ambiguous, ask a concise clarification question before running a command.
+* Never assume a workspace or thread that the user has not referenced.
+* If the user does not name or contextually reference a workspace for a workspace/thread/message operation, ask which workspace to use before running a command.
+* If the user names or contextually references a thread but does not name or contextually reference its workspace, ask which workspace contains that thread before running a command.
+* When the user explicitly uses contextual references such as "current workspace", "this thread", "the thread just created", "that workspace", or similar references, resolve them from the available conversation context only when the reference is unambiguous.
+* If multiple plausible matches exist, ask the user to choose.
+
+For `send-llm-message`:
+
+* Require all four values to be explicitly named or explicitly referenced in the current request:
+  * workspace
+  * thread
+  * LLM provider
+  * LLM model
+* If any of those four values are missing or ambiguous, ask for the missing values before running the command.
+* Use provider/model only from:
+  * `prepare.models`
+  * `list-llm-providers`
+  * `list-llm-models`
+* Never use `prepare.agents[].models` for `send-llm-message`.
+* Prefer provider `realtimexai` unless the user explicitly asks for local `nodellama`.
+* Only choose a model id that exists in the selected provider's LLM model list.
+* If the requested model is unavailable, ask which available model to use instead.
+
+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.