@realtimex/sdk 1.7.28 → 2.0.1

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

@@ -1,102 +0,0 @@
----
-name: realtimex-moderator-sdk
-description: Control and interact with the RealTimeX application through its Node.js SDK. Use for workspaces, threads, agents, activities, LLM chat, vector store, MCP tools, ACP sessions, desktop terminal/browser sessions, chat channels, TTS/STT, and other RealTimeX platform APIs. Load detailed version-matched instructions with `rtx.js skills get <topic>`.
-generated: 2026-06-02
-sdk_version: 1.7.28
----
-
-# RealTimeX Moderator SDK
-
-SDK-backed control of the local RealTimeX platform (`http://localhost:3001`) using `@realtimex/sdk` **v1.7.28**.
-
-This file is the discovery stub. Load workflow content from the bundled CLI so instructions match the installed SDK version.
-
-`<SKILL_DIR>` below means this skill directory.
-
-## Start Here
-
-```bash
-SKILL=<SKILL_DIR>/scripts/rtx.js
-ENV=--env-dir=<cwd>
-
-node "$SKILL" skills get core $ENV
-node "$SKILL" skills get core --full $ENV
-```
-
-The CLI serves skill content generated from the installed SDK source and generated references.
-
-## Specialized Skills
-
-Load the smallest relevant topic before acting:
-
-```bash
-node "$SKILL" skills list $ENV
-node "$SKILL" skills get workspaces $ENV
-node "$SKILL" skills get agents $ENV
-node "$SKILL" skills get terminal $ENV
-node "$SKILL" skills get browser $ENV
-node "$SKILL" skills get channels $ENV
-node "$SKILL" skills get llm $ENV
-node "$SKILL" skills get mcp $ENV
-node "$SKILL" skills get activities $ENV
-node "$SKILL" skills get api:v1-channels --full $ENV
-```
-
-File fallback is also available under `references/`, especially:
-
-- `references/quickstart.md`
-- `references/permissions.md`
-- `references/workspaces.md`
-- `references/browser.md`
-- `references/channels.md`
-- `references/api-reference/index.md`
-
-## Quick Commands
-
-```bash
-node "$SKILL" ping $ENV
-node "$SKILL" context $ENV
-node "$SKILL" workspaces $ENV
-node "$SKILL" threads <workspace-slug> $ENV
-node "$SKILL" agents $ENV
-node "$SKILL" help
-```
-
-For custom scripts:
-
-```js
-const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
-const { sdk, context } = await initSDK();
-```
-
-Scripts using the SDK must exit explicitly with `process.exit(0)` or `process.exit(1)`.
-
-## Critical Routing Rules
-
-- Visible terminal work: load `skills get terminal`; use `sdk.desktopRuntimeSessions.*`, not ACP, unless the user explicitly asks for headless ACP.
-- RealTimeX Browser work: load `skills get browser`; use `sdk.desktopBrowser.*` for session/tab control, then use `agent-browser` against the CDP port for page interaction.
-- External chat channels: load `skills get channels`; use `sdk.v1.channels.*`; LocalApps using `x-app-id` need `channels.manage`.
-- Workspace/thread context: load `skills get workspaces`; do not guess workspace/thread when context is unknown.
-
-## Known Source Issues
-
-| # | Issue |
-|---|-------|
-| 1 | 'sdk.webhook.triggerAgent()' sends 'event: "task.trigger"' — server expects '"trigger-agen |
-| 2 | 'sdk.task.start/complete/fail' take positional '(taskUuid, ...)' — NOT '{ task_uuid }' obj |
-| 3 | 'sdk.activities.list()' returns 'Activity[]' directly — NOT '{ activities: [...] }' |
-| 4 | 'sdk.llm.chat()' response is 'res.response?.content' — NOT 'choices[0].message.content' |
-| 5 | 'sdk.llm.chatStream()' yields 'chunk.textResponse' — NOT 'choices[0].delta.content' |
-| 6 | 'sdk.llm.embedAndStore()' takes '{ texts: string[], documentId?, workspaceId?, ... }' — NO |
-| 7 | 'sdk.llm.vectors.query()' takes a raw 'number[]' embedding — NOT a text string |
-| 8 | 'sdk.llm.vectors.delete()' requires '{ deleteAll: true }' — delete-by-ID not supported |
-| 9 | 'sdk.mcp.getServers()' takes a plain string — NOT '{ provider: "all" }' |
-| 10 | 'getAgents/getWorkspaces/getThreads/getTask' live on 'sdk.api.*' — NOT directly on 'sdk.*' |
-| 11 | ACP 'streamChat' uses named SSE ('event:' line); 'text_delta.data.type === "thinking"' = i |
-| 12 | ACP sessions stall without 'approvalPolicy: "approve-all"' when tools need permission |
-
-For evidence and corrected usage:
-
-```bash
-node "$SKILL" skills get known-issues $ENV
-```

package/skills/realtimex-moderator-sdk/references/activities.md

@@ -1,14 +0,0 @@
-# Activities
-
-> Generated workflow guide · SDK **1.7.28** · 2026-06-02
-
-Use `sdk.activities` for activity CRUD.
-
-Required permissions: `activities.read` and/or `activities.write`.
-
-```js
-await sdk.activities.list({ status: "pending" });
-await sdk.activities.insert({ type: "note", text: "..." });
-await sdk.activities.update(id, updates);
-await sdk.activities.delete(id);
-```

package/skills/realtimex-moderator-sdk/references/agents.md

@@ -1,13 +0,0 @@
-# Agents
-
-> Generated workflow guide · SDK **1.7.28** · 2026-06-02
-
-Use `sdk.api` for lightweight lists and `sdk.agent` / `sdk.acpAgent` for execution.
-
-```js
-await sdk.api.getAgents();
-await sdk.webhook.triggerAgent(agentSlug, workspaceSlug, message);
-await sdk.agent.chat({ workspaceSlug, agent: agentSlug, message });
-```
-
-Use ACP only for headless/background CLI agent sessions. Use `sdk.desktopRuntimeSessions` for visible Electron terminals.

package/skills/realtimex-moderator-sdk/references/api-reference/acpagent.md

@@ -1,105 +0,0 @@
-# sdk.acpAgent — ACP CLI Agent Sessions
-
-> Auto-generated from `@realtimex/sdk` source · v**1.7.28** · 2026-06-02
-
-## `AcpAgentModule`
-
-### Methods
-
-```ts
-// List available CLI agents. Pass includeModels to get model lists per agent.
-async listAgents(opts?: { includeModels?: boolean; }): Promise<AcpAgentInfo[]>
-
-// Create and initialize a new ACP session. Spawns the CLI agent process.
-async createSession(options: AcpSessionOptions): Promise<AcpSession>
-
-// Get session status and runtime options.
-async getSession(sessionKey: string): Promise<AcpSessionStatus>
-
-// List active ACP sessions owned by this app.
-async listSessions(): Promise<AcpSessionStatus[]>
-
-// Update runtime options (applied on next turn).
-async patchSession(sessionKey: string, patch: AcpRuntimeOptionPatch): Promise<void>
-
-// Close session and stop the agent process.
-async closeSession(sessionKey: string, reason?: string): Promise<void>
-
-// Synchronous turn — waits for completion, returns full response.
-async chat(sessionKey: string, message: string, attachments?: AcpAttachment[]): Promise<AcpChatResponse>
-
-// Streaming turn via SSE. Yields events as they arrive.
-async *streamChat(sessionKey: string, message: string, attachments?: AcpAttachment[]): AsyncIterableIterator<AcpStreamEvent>
-
-// Cancel the active turn on a session.
-async cancelTurn(sessionKey: string, reason?: string): Promise<void>
-
-// Resolve a pending permission request (call while SSE stream is active).
-async resolvePermission(sessionKey: string, decision: AcpPermissionDecision): Promise<
-
-// Convenience: create session + first sync chat in one call.
-async startChat(message: string, options: AcpSessionOptions): Promise<
-```
-
-## `AcpSessionOptions`
-
-```ts
-agent_id: string
-cwd?: string
-label?: string
-model?: string
-approvalPolicy?: "approve-all" | "approve-reads" | "deny-all"
-forwardedProvider?: string
-```
-
-## `AcpSession`
-
-```ts
-session_key: string
-agent_id: string
-state: "initializing" | "ready" | "stale" | "closed"
-backend_id: string
-created_at: string
-```
-
-## `AcpSessionStatus`
-
-```ts
-runtime_options: AcpRuntimeOptionPatch
-last_activity_at: string | null
-last_error?: string
-```
-
-## `AcpRuntimeOptionPatch`
-
-```ts
-model?: string
-cwd?: string
-timeoutSeconds?: number
-runtimeMode?: string
-approvalPolicy?: "approve-all" | "approve-reads" | "deny-all"
-```
-
-## `AcpAttachment`
-
-```ts
-contentString: string
-mime: string
-```
-
-## `AcpChatResponse`
-
-```ts
-text: string
-stop_reason?: string
-```
-
-## `AcpStreamEvent`
-
-## `AcpPermissionDecision`
-
-```ts
-requestId: string
-optionId: string
-outcome?: string
-```

package/skills/realtimex-moderator-sdk/references/api-reference/activities.md

@@ -1,24 +0,0 @@
-# sdk.activities — Activities CRUD
-
-> Auto-generated from `@realtimex/sdk` source · v**1.7.28** · 2026-06-02
-
-## `ActivitiesModule`
-
-### Methods
-
-```ts
-// Request a single permission from Electron via internal API
-async insert(rawData: Record<string, unknown>): Promise<Activity>
-
-// Update an existing activity
-async update(id: string, updates: Partial<Activity>): Promise<Activity>
-
-// Delete an activity
-async delete(id: string): Promise<void>
-
-// Get a single activity by ID
-async get(id: string): Promise<Activity | null>
-
-// List activities with optional filters
-async list(options?: { status?: string; limit?: number; offset?: number }): Promise<Activity[]>
-```

package/skills/realtimex-moderator-sdk/references/api-reference/agent.md

@@ -1,27 +0,0 @@
-# sdk.agent — LLM Agent Sessions (REST/SSE)
-
-> Auto-generated from `@realtimex/sdk` source · v**1.7.28** · 2026-06-02
-
-## `AgentModule`
-
-### Methods
-
-```ts
-// Create a new agent session
-async createSession(options?: AgentSessionOptions): Promise<AgentSession>
-
-// Chat within a session (synchronous)
-async chat(sessionId: string, message: string): Promise<AgentChatResponse>
-
-// Stream chat within a session
-async *streamChat(sessionId: string, message: string): AsyncIterableIterator<StreamChunkEvent>
-
-// Get session information
-async getSession(sessionId: string): Promise<AgentSessionInfo>
-
-// Close and delete a session
-async closeSession(sessionId: string): Promise<void>
-
-// Helper: Create session and send first message in one call
-async startChat(message: string, options?: AgentSessionOptions): Promise<
-```

package/skills/realtimex-moderator-sdk/references/api-reference/api.md

@@ -1,17 +0,0 @@
-# sdk.api — Agents, Workspaces, Threads, Tasks
-
-> Auto-generated from `@realtimex/sdk` source · v**1.7.28** · 2026-06-02
-
-## `ApiModule`
-
-### Methods
-
-```ts
-async getAgents(): Promise<Agent[]>
-
-async getWorkspaces(): Promise<Workspace[]>
-
-async getThreads(workspaceSlug: string): Promise<Thread[]>
-
-async getTask(taskUuid: string): Promise<Task>
-```

package/skills/realtimex-moderator-sdk/references/api-reference/auth.md

@@ -1,36 +0,0 @@
-# sdk.auth — Auth Token
-
-> Auto-generated from `@realtimex/sdk` source · v**1.7.28** · 2026-06-02
-
-## `AuthModule`
-
-### Methods
-
-```ts
-// Push a Supabase access token to the Main App.
-async syncSupabaseToken(token: string): Promise<SyncTokenResponse>
-
-// Retrieve the current Keycloak access token from Main App.
-async getAccessToken(): Promise<AuthTokenResponse | null>
-```
-
-## `AuthTokenResponse`
-
-> Auth Module - Authentication helpers for RealtimeX SDK
-
-```ts
-token: string
-hasToken: boolean
-syncedAt: string | null
-source: string | null
-```
-
-## `SyncTokenResponse`
-
-```ts
-success: boolean
-message: string
-hasToken: boolean
-syncedAt: string | null
-source: string | null
-```

package/skills/realtimex-moderator-sdk/references/api-reference/contract.md

@@ -1,27 +0,0 @@
-# sdk.contract — Local App Contract
-
-> Auto-generated from `@realtimex/sdk` source · v**1.7.28** · 2026-06-02
-
-## `ContractModule`
-
-### Methods
-
-```ts
-async getLocalAppV1(forceRefresh = false): Promise<LocalAppContractDefinition>
-
-async listCapabilities(forceRefresh = false): Promise<ContractCapability[]>
-
-async searchCapabilities(query: string): Promise<ContractCapability[]>
-
-async describeCapability(capabilityId: string): Promise<ContractCapability>
-
-async search(query: string): Promise<ContractCapability[]>
-
-async describe(capabilityId: string): Promise<ContractCapability>
-
-async invoke(payload: ContractInvokePayload): Promise<TriggerAgentResponse>
-
-getCachedCatalogHash(): string | null
-
-clearCache(): void
-```

package/skills/realtimex-moderator-sdk/references/api-reference/core.md

@@ -1,40 +0,0 @@
-# Core — RealtimeXSDK
-
-> Auto-generated from `@realtimex/sdk` source · v**1.7.28** · 2026-06-02
-
-## `RealtimeXSDK`
-
-### Public Properties
-
-- `activities: ActivitiesModule`
-- `webhook: WebhookModule`
-- `api: ApiModule`
-- `task: TaskModule`
-- `port: PortModule`
-- `llm: LLMModule`
-- `tts: TTSModule`
-- `stt: STTModule`
-- `agent: AgentModule`
-- `acpAgent: AcpAgentModule`
-- `mcp: MCPModule`
-- `contract: ContractModule`
-- `contractRuntime: ContractRuntime`
-- `database: DatabaseModule`
-- `auth: AuthModule`
-- `credentials: CredentialsModule`
-- `v1: V1ApiNamespace | undefined`
-- `desktopRuntimeSessions: V1DesktopRuntimeSessionsModule | undefined`
-- `desktopBrowser: V1DesktopBrowserModule | undefined`
-
-### Methods
-
-```ts
-// Developer API (v1) — requires apiKey to be set in config.
-async register(permissions?: string[]): void
-
-// Get environment variable (works in Node.js and browser)
-async ping(): Promise<
-
-// Get the absolute path to the data directory for this app.
-async getAppDataDir(): Promise<string>
-```

package/skills/realtimex-moderator-sdk/references/api-reference/database.md

@@ -1,24 +0,0 @@
-# sdk.database — Supabase Config
-
-> Auto-generated from `@realtimex/sdk` source · v**1.7.28** · 2026-06-02
-
-## `DatabaseModule`
-
-### Methods
-
-```ts
-// Get the Supabase database configuration for this app.
-async getConfig(): Promise<DatabaseConfig>
-```
-
-## `DatabaseConfig`
-
-> Database Module - Retrieve Supabase config from RealtimeX Main App
-
-```ts
-url: string
-anonKey: string
-mode: 'compatible' | 'custom'
-tables: string[]
-max_concurrent_tasks: number
-```

package/skills/realtimex-moderator-sdk/references/api-reference/index.md

@@ -1,43 +0,0 @@
-# API Reference Index
-
-> Auto-generated from `@realtimex/sdk` source · v**1.7.28** · 2026-06-02
-
-Use these files for exact SDK signatures. Topic guides in `references/*.md` explain workflows.
-
-| Module | File |
-|---|---|
-| Core — RealtimeXSDK | [core.md](./core.md) |
-| sdk.api — Agents, Workspaces, Threads, Tasks | [api.md](./api.md) |
-| sdk.activities — Activities CRUD | [activities.md](./activities.md) |
-| sdk.task — Task Lifecycle Reporting | [task.md](./task.md) |
-| sdk.webhook — Webhook Trigger | [webhook.md](./webhook.md) |
-| sdk.llm — LLM Chat, Embed, Vector Search | [llm.md](./llm.md) |
-| sdk.mcp — MCP Server Tools | [mcp.md](./mcp.md) |
-| sdk.acpAgent — ACP CLI Agent Sessions | [acpagent.md](./acpagent.md) |
-| sdk.agent — LLM Agent Sessions (REST/SSE) | [agent.md](./agent.md) |
-| sdk.tts — Text-to-Speech | [tts.md](./tts.md) |
-| sdk.stt — Speech-to-Text | [stt.md](./stt.md) |
-| sdk.contract — Local App Contract | [contract.md](./contract.md) |
-| sdk.database — Supabase Config | [database.md](./database.md) |
-| sdk.auth — Auth Token | [auth.md](./auth.md) |
-| sdk.port — Port Management | [port.md](./port.md) |
-| sdk.v1.acpAuth — v1 Acp Auth | [v1-acpauth.md](./v1-acpauth.md) |
-| sdk.v1.acpCommands — v1 Acp Commands | [v1-acpcommands.md](./v1-acpcommands.md) |
-| sdk.v1.admin — v1 Admin | [v1-admin.md](./v1-admin.md) |
-| sdk.v1.auth — v1 Auth | [v1-auth.md](./v1-auth.md) |
-| sdk.v1.channels — v1 Channels | [v1-channels.md](./v1-channels.md) |
-| sdk.v1.credentials — v1 Credentials | [v1-credentials.md](./v1-credentials.md) |
-| sdk.v1.customThemes — v1 Custom Themes | [v1-customthemes.md](./v1-customthemes.md) |
-| sdk.v1.desktopBrowser — v1 Desktop Browser | [v1-desktopbrowser.md](./v1-desktopbrowser.md) |
-| sdk.v1.desktopEmbed — v1 Desktop Embed | [v1-desktopembed.md](./v1-desktopembed.md) |
-| sdk.v1.desktopRuntimeSessions — v1 Desktop Runtime Sessions | [v1-desktopruntimesessions.md](./v1-desktopruntimesessions.md) |
-| sdk.v1.document — v1 Document | [v1-document.md](./v1-document.md) |
-| sdk.v1.embed — v1 Embed | [v1-embed.md](./v1-embed.md) |
-| sdk.v1.openAI — v1 Open A I | [v1-openai.md](./v1-openai.md) |
-| sdk.v1.sttApi — v1 Stt Api | [v1-sttapi.md](./v1-sttapi.md) |
-| sdk.v1.system — v1 System | [v1-system.md](./v1-system.md) |
-| sdk.v1.thread — v1 Thread | [v1-thread.md](./v1-thread.md) |
-| sdk.v1.users — v1 Users | [v1-users.md](./v1-users.md) |
-| sdk.v1.workspace — v1 Workspace | [v1-workspace.md](./v1-workspace.md) |
-
-The legacy aggregate reference remains available at `../api-reference.md`.

package/skills/realtimex-moderator-sdk/references/api-reference/llm.md

@@ -1,176 +0,0 @@
-# sdk.llm — LLM Chat, Embed, Vector Search
-
-> Auto-generated from `@realtimex/sdk` source · v**1.7.28** · 2026-06-02
-
-## `VectorStore`
-
-### Methods
-
-```ts
-// Request a single permission from Electron via internal API
-async upsert(vectors: VectorRecord[], options: VectorUpsertOptions = {}): Promise<VectorUpsertResponse>
-
-// Query similar vectors by embedding
-async query(vector: number[], options: VectorQueryOptions = {}): Promise<VectorQueryResponse>
-
-// Delete vectors from storage
-async delete(options: VectorDeleteOptions): Promise<VectorDeleteResponse>
-
-// List all available workspaces (namespaces) for this app
-async listWorkspaces(): Promise<VectorListWorkspacesResponse>
-
-// Register a custom vector database configuration for this app
-async registerConfig(provider: string, config: Record<string, any>): Promise<VectorRegisterResponse>
-
-// List all supported vector database providers and their configuration requirements
-async listProviders(): Promise<VectorProvidersResponse>
-
-// Get the current vector database configuration for this app
-async getConfig(): Promise<VectorConfigResponse>
-```
-
-## `LLMModule`
-
-### Public Properties
-
-- `vectors: VectorStore`
-
-### Methods
-
-```ts
-// Request a single permission from Electron via internal API
-async chatProviders(): Promise<ProvidersResponse>
-
-// Get only configured embedding providers
-async embedProviders(): Promise<ProvidersResponse>
-
-// Send a chat completion request (synchronous)
-async chat(messages: ChatMessage[], options: ChatOptions = {}): Promise<ChatResponse>
-
-// Send a streaming chat completion request (SSE)
-async *chatStream(messages: ChatMessage[], options: ChatOptions = {}): AsyncGenerator<StreamChunk, void, unknown>
-
-// Generate vector embeddings from text
-async embed(input: string | string[], options: EmbedOptions = {}): Promise<EmbedResponse>
-
-// Helper: Embed text and store as vectors in one call
-async embedAndStore(params: { texts: string[]; documentId?: string; workspaceId?: string; idPrefix?: string; provider?: string; model?: string; }): Promise<VectorUpsertResponse>
-
-// Helper: Search similar documents by text query
-async search(query: string, options: VectorQueryOptions = {}): Promise<VectorQueryResult[]>
-```
-
-## `ChatOptions`
-
-```ts
-model?: string
-provider?: string
-temperature?: number
-max_tokens?: number
-response_format?: { type: string }
-```
-
-## `ChatResponse`
-
-```ts
-success: boolean
-response?: {
-content: string
-model: string
-provider?: string
-metrics?: {
-prompt_tokens: number
-completion_tokens: number
-total_tokens: number
-duration?: number
-outputTps?: number
-error?: string
-code?: string
-```
-
-## `StreamChunk`
-
-```ts
-uuid?: string
-type?: string
-textResponse?: string
-close?: boolean
-error?: boolean
-```
-
-## `EmbedOptions`
-
-```ts
-provider?: string
-model?: string
-```
-
-## `EmbedResponse`
-
-```ts
-success: boolean
-embeddings?: number[][]
-provider?: string
-model?: string
-dimensions?: number
-error?: string
-code?: string
-errors?: string[]
-```
-
-## `VectorRecord`
-
-```ts
-id: string
-vector: number[]
-metadata?: {
-text?: string
-documentId?: string
-workspaceId?: string
-```
-
-## `VectorUpsertOptions`
-
-```ts
-workspaceId?: string
-```
-
-## `VectorQueryOptions`
-
-```ts
-topK?: number
-filter?: {
-workspaceId?: string
-documentId?: string
-workspaceId?: string
-provider?: string
-model?: string
-```
-
-## `VectorQueryResult`
-
-```ts
-id: string
-score: number
-metadata?: {
-text?: string
-documentId?: string
-workspaceId?: string
-```
-
-## `VectorDeleteOptions`
-
-```ts
-workspaceId?: string
-deleteAll: true
-```
-
-## `VectorListWorkspacesResponse`
-
-```ts
-success: boolean
-workspaces?: string[]
-error?: string
-code?: string
-error_message?: string
-```