@realtimex/sdk 1.7.7 → 1.7.9

package/dist/v1/index.js

@@ -28,10 +28,10 @@ __export(v1_exports, {
   V1AdminModule: () => V1AdminModule,
   V1ApiNamespace: () => V1ApiNamespace,
   V1AuthModule: () => V1AuthModule,
+  V1DesktopRuntimeSessionsModule: () => V1DesktopRuntimeSessionsModule,
   V1DocumentModule: () => V1DocumentModule,
   V1EmbedModule: () => V1EmbedModule,
   V1OpenAIModule: () => V1OpenAIModule,
-  V1RuntimeSessionsModule: () => V1RuntimeSessionsModule,
   V1SystemModule: () => V1SystemModule,
   V1ThreadModule: () => V1ThreadModule,
   V1UsersModule: () => V1UsersModule,
@@ -533,77 +533,6 @@ var V1SystemModule = class {
   }
 };
 
-// src/v1/modules/v1RuntimeSessions.ts
-var V1RuntimeSessionsModule = class {
-  constructor(client) {
-    this.client = client;
-  }
-  /**
-   * Resolve the desktop shell launch working directory for a workspace or thread context.
-   * @see POST /v1/runtime-sessions/desktop-shell/launch-spec
-   */
-  async desktopShellLaunchSpec(body) {
-    return this.client.request("POST", `/v1/runtime-sessions/desktop-shell/launch-spec`, body);
-  }
-  /**
-   * Evaluate the runtime terminal permission policy for a pending CLI action.
-   * @see POST /v1/runtime-sessions/terminal-permissions/evaluate
-   */
-  async terminalPermissionsEvaluate(body) {
-    return this.client.request("POST", `/v1/runtime-sessions/terminal-permissions/evaluate`, body);
-  }
-  /**
-   * Resolve the CLI agent terminal launch command and working directory.
-   * @see POST /v1/runtime-sessions/cli-agent/launch-spec
-   */
-  async cliAgentLaunchSpec(body) {
-    return this.client.request("POST", `/v1/runtime-sessions/cli-agent/launch-spec`, body);
-  }
-  /**
-   * Create a persistent ACP-backed CLI agent runtime session.
-   * @see POST /v1/runtime-sessions/cli-agent
-   */
-  async cliAgent(body) {
-    return this.client.request("POST", `/v1/runtime-sessions/cli-agent`, body);
-  }
-  /**
-   * Stream a chat turn to an existing CLI agent runtime session using Server-Sent Events.
-   * @see POST /v1/runtime-sessions/cli-agent/{sessionKey}/chat/stream
-   */
-  // @streaming-stub — implement SSE parsing in overrides/v1RuntimeSessionsStreaming.ts
-  async cliAgentChatStream(sessionKey, body) {
-    return this.client.requestRaw("POST", `/v1/runtime-sessions/cli-agent/${sessionKey}/chat/stream`, body);
-  }
-  /**
-   * Resolve a pending permission request for a CLI agent runtime session.
-   * @see POST /v1/runtime-sessions/cli-agent/{sessionKey}/permission
-   */
-  async cliAgentPermission(sessionKey, body) {
-    return this.client.request("POST", `/v1/runtime-sessions/cli-agent/${sessionKey}/permission`, body);
-  }
-  /**
-   * Cancel the current CLI turn for an active runtime session.
-   * @see POST /v1/runtime-sessions/cli-agent/{sessionKey}/cancel
-   */
-  async cliAgentCancel(sessionKey, body) {
-    return this.client.request("POST", `/v1/runtime-sessions/cli-agent/${sessionKey}/cancel`, body);
-  }
-  /**
-   * Close a CLI agent runtime session and clear its control-plane metadata.
-   * @see DELETE /v1/runtime-sessions/cli-agent/{sessionKey}
-   */
-  async deleteCliAgent(sessionKey) {
-    return this.client.request("DELETE", `/v1/runtime-sessions/cli-agent/${sessionKey}`);
-  }
-  /**
-   * Fetch the current state and runtime options for a CLI agent session.
-   * @see GET /v1/runtime-sessions/cli-agent/{sessionKey}
-   */
-  async getCliAgent(sessionKey) {
-    return this.client.request("GET", `/v1/runtime-sessions/cli-agent/${sessionKey}`);
-  }
-};
-
 // src/v1/modules/v1Thread.ts
 var V1ThreadModule = class {
   constructor(client) {
@@ -759,6 +688,69 @@ var V1EmbedModule = class {
   }
 };
 
+// src/v1/modules/v1DesktopRuntimeSessions.ts
+var V1DesktopRuntimeSessionsModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Open the shared terminal launcher in the Electron desktop app.
+   * @see POST /sdk/desktop/runtime-sessions/open-launcher
+   */
+  async openLauncher(body) {
+    return this.client.request("POST", `/sdk/desktop/runtime-sessions/open-launcher`, body);
+  }
+  /**
+   * Launch a local PTY-backed shell terminal in the Electron desktop app.
+   * @see POST /sdk/desktop/runtime-sessions/launch-terminal-shell
+   */
+  async launchTerminalShell(body) {
+    return this.client.request("POST", `/sdk/desktop/runtime-sessions/launch-terminal-shell`, body);
+  }
+  /**
+   * Launch a local PTY-backed CLI agent terminal in the Electron desktop app.
+   * @see POST /sdk/desktop/runtime-sessions/launch-terminal-cli-agent
+   */
+  async launchTerminalCliAgent(body) {
+    return this.client.request("POST", `/sdk/desktop/runtime-sessions/launch-terminal-cli-agent`, body);
+  }
+  /**
+   * List desktop PTY-backed runtime sessions currently known to the Electron app.
+   * @see GET /sdk/desktop/runtime-sessions
+   */
+  async listRuntimeSessions() {
+    return this.client.request("GET", `/sdk/desktop/runtime-sessions`);
+  }
+  /**
+   * Fetch one desktop PTY-backed runtime session by runtime session ID or PTY session ID.
+   * @see GET /sdk/desktop/runtime-sessions/{sessionId}
+   */
+  async getRuntimeSession(sessionId) {
+    return this.client.request("GET", `/sdk/desktop/runtime-sessions/${sessionId}`);
+  }
+  /**
+   * Close an existing desktop runtime session.
+   * @see DELETE /sdk/desktop/runtime-sessions/{sessionId}
+   */
+  async deleteRuntimeSession(sessionId) {
+    return this.client.request("DELETE", `/sdk/desktop/runtime-sessions/${sessionId}`);
+  }
+  /**
+   * Write input to an existing desktop runtime session. Use `message` to submit a CLI turn or `input` for raw PTY data.
+   * @see POST /sdk/desktop/runtime-sessions/{sessionId}/write
+   */
+  async write(sessionId, body) {
+    return this.client.request("POST", `/sdk/desktop/runtime-sessions/${sessionId}/write`, body);
+  }
+  /**
+   * Approve or deny a pending desktop runtime session action.
+   * @see POST /sdk/desktop/runtime-sessions/{sessionId}/permission
+   */
+  async permission(sessionId, body) {
+    return this.client.request("POST", `/sdk/desktop/runtime-sessions/${sessionId}/permission`, body);
+  }
+};
+
 // src/v1/namespace.ts
 var V1ApiNamespace = class {
   // [GENERATED-PROPS-END]
@@ -769,11 +761,11 @@ var V1ApiNamespace = class {
     this.document = new V1DocumentModule(this._client);
     this.workspace = new V1WorkspaceModule(this._client);
     this.system = new V1SystemModule(this._client);
-    this.runtimeSessions = new V1RuntimeSessionsModule(this._client);
     this.thread = new V1ThreadModule(this._client);
     this.users = new V1UsersModule(this._client);
     this.openai = new V1OpenAIModule(this._client);
     this.embed = new V1EmbedModule(this._client);
+    this.desktopRuntimeSessions = new V1DesktopRuntimeSessionsModule(this._client);
   }
 };
 
@@ -900,10 +892,10 @@ async function uploadFileToFolder(client, file, folderName, options = {}) {
   V1AdminModule,
   V1ApiNamespace,
   V1AuthModule,
+  V1DesktopRuntimeSessionsModule,
   V1DocumentModule,
   V1EmbedModule,
   V1OpenAIModule,
-  V1RuntimeSessionsModule,
   V1SystemModule,
   V1ThreadModule,
   V1UsersModule,

package/dist/v1/index.mjs

@@ -7,16 +7,16 @@ import {
   V1AdminModule,
   V1ApiNamespace,
   V1AuthModule,
+  V1DesktopRuntimeSessionsModule,
   V1DocumentModule,
   V1EmbedModule,
   V1OpenAIModule,
-  V1RuntimeSessionsModule,
   V1SystemModule,
   V1ThreadModule,
   V1UsersModule,
   V1WorkspaceModule,
   ValidationError
-} from "../chunk-EMMHP4JM.mjs";
+} from "../chunk-3DVGTGOK.mjs";
 
 // src/v1/overrides/v1WorkspaceStreaming.ts
 async function* streamWorkspaceChat(client, slug, body) {
@@ -140,10 +140,10 @@ export {
   V1AdminModule,
   V1ApiNamespace,
   V1AuthModule,
+  V1DesktopRuntimeSessionsModule,
   V1DocumentModule,
   V1EmbedModule,
   V1OpenAIModule,
-  V1RuntimeSessionsModule,
   V1SystemModule,
   V1ThreadModule,
   V1UsersModule,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.7.7",
+    "version": "1.7.9",
     "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,13 +1,13 @@
 ---
 name: realtimex-moderator-sdk
 description: Control and interact with the RealTimeX application through its Node.js SDK. This skill should be used when users want to manage workspaces, threads, agents, activities, LLM chat, vector store, MCP tools, ACP agent sessions, TTS/STT, or any other RealTimeX platform feature via the API. All method signatures are verified against the SDK source code.
-generated: 2026-05-05
-sdk_version: 1.7.7
+generated: 2026-05-06
+sdk_version: 1.7.9
 ---
 
 # RealTimeX Moderator (SDK Source-Verified)
 
-Interact with the RealTimeX platform (`http://localhost:3001`) using `@realtimex/sdk` **v1.7.7**. Authentication is automatic when running inside RealtimeX.
+Interact with the RealTimeX platform (`http://localhost:3001`) using `@realtimex/sdk` **v1.7.9**. Authentication is automatic when running inside RealtimeX.
 
 `<SKILL_DIR>` below refers to the directory containing this SKILL.md.
 
@@ -24,6 +24,10 @@ node "$SKILL" agents                                   $ENV
 node "$SKILL" workspaces                               $ENV
 node "$SKILL" threads <workspace-slug>                 $ENV
 node "$SKILL" trigger-agent <agent> <workspace> <msg>  $ENV
+node "$SKILL" terminal-launch-cli-agent claude claude-cli "what is current working dir" --workspace=<slug> --thread=<slug>  $ENV
+node "$SKILL" terminal-launch-shell --workspace=<slug> --thread=<slug> --command="pwd"  $ENV
+node "$SKILL" terminal-sessions --workspace=<slug>     $ENV
+node "$SKILL" terminal-write <session-id> "continue"   $ENV
 node "$SKILL" acp-chat qwen-cli "question" --cwd=<path>  $ENV
 node "$SKILL" llm-chat "message"                       $ENV
 node "$SKILL" activities --status=pending              $ENV
@@ -44,15 +48,95 @@ Scripts using the SDK must exit explicitly — `process.exit(0)` on success, `pr
 
 ---
 
-## Runtime Sessions
+## Desktop Terminal Sessions
 
-In this SDK, **Runtime Sessions** means the CLI Agent in **Terminal mode**. Use `sdk.agent.*` for that path.
+For anything that says **launch terminal**, **open shell**, **open Claude/Gemini in terminal**, or **send another message to an existing terminal session**, use:
 
-This is separate from ACP mode:
-- `sdk.agent.*` = Runtime Sessions = CLI Agent / Terminal mode
-- `sdk.acpAgent.*` = ACP-backed CLI agent sessions
+- `sdk.desktopRuntimeSessions.*`
 
-If a user refers to the v1/OpenAPI tag `Runtime Sessions`, interpret that as the Terminal mode session flow, not ACP.
+Do **not** use ACP for that unless the user explicitly asks for a headless ACP session.
+
+### Use desktop terminal sessions for
+- opening a visible terminal in the Electron app
+- launching a shell session
+- launching a CLI agent in a terminal tab/panel
+- listing desktop terminal sessions
+- writing more input to an existing terminal session
+- approving or denying a pending terminal action
+- closing a terminal session
+
+### Use ACP only for
+- headless background agent sessions
+- persistent server-side automation
+- `acp-chat`, `acp-stream`, `acp-session-*`
+
+### Correct SDK namespace
+
+```js
+sdk.desktopRuntimeSessions
+```
+
+Compatibility:
+- `sdk.desktopRuntimeSessions` is the preferred alias
+- `sdk.v1.desktopRuntimeSessions` still exists for backward compatibility
+- there is no `sdk.v1.runtimeSessions`
+
+### Required payloads
+
+Launch terminal CLI agent:
+
+```js
+await sdk.desktopRuntimeSessions.launchTerminalCliAgent({
+  workspaceSlug: "agent-heartbeat",
+  threadSlug: "ambient-agent-week-agent-heartbeat-2026-w17",
+  agentName: "claude",        // required
+  providerId: "claude-cli",   // strongly recommended
+  presentationMode: "panel",  // optional: "panel" | "tab"
+  message: "what is current working dir"
+});
+```
+
+Important:
+- `agentName` is the agent label, like `"claude"` or `"gemini"`
+- `providerId` is the launcher/provider id, like `"claude-cli"` or `"gemini-cli"`
+- Do not pass `agentName: "claude-cli"` unless that is truly the agent label shown by the app
+
+Launch terminal shell:
+
+```js
+await sdk.desktopRuntimeSessions.launchTerminalShell({
+  workspaceSlug: "agent-heartbeat",
+  threadSlug: "ambient-agent-week-agent-heartbeat-2026-w17",
+  presentationMode: "panel",
+  initialCommand: "pwd",
+  initialCommandMode: "direct"
+});
+```
+
+Manage existing terminal sessions:
+
+```js
+await sdk.desktopRuntimeSessions.listRuntimeSessions();
+await sdk.desktopRuntimeSessions.getRuntimeSession("cli-agent:pty-123");
+await sdk.desktopRuntimeSessions.write("cli-agent:pty-123", {
+  message: "continue"
+});
+await sdk.desktopRuntimeSessions.permission("cli-agent:pty-123", {
+  outcome: "approved",
+  actionId: "terminal-action-1"
+});
+await sdk.desktopRuntimeSessions.deleteRuntimeSession("cli-agent:pty-123");
+```
+
+### Preferred decision rule
+
+If the user says:
+- "launch in terminal"
+- "open Claude in terminal"
+- "ask Gemini in terminal"
+- "open a shell and run pwd"
+
+then prefer `sdk.desktopRuntimeSessions.*`, not ACP.
 
 ---
 

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

@@ -1,6 +1,6 @@
 # RealTimeX SDK — API Reference
 
-> Auto-generated from `@realtimex/sdk` source · v**1.7.7** · 2026-05-05
+> Auto-generated from `@realtimex/sdk` source · v**1.7.9** · 2026-05-06
 
 **Package:** `@realtimex/sdk` (CJS) · **Server:** `http://localhost:3001`
 **Developer Mode auth:** `Authorization: Bearer <apiKey>`
@@ -30,6 +30,77 @@
 
 ---
 
+## sdk.desktopRuntimeSessions — Desktop Terminal Sessions
+
+Use this module for visible Electron terminal sessions. This is the correct path for:
+- launching a shell terminal
+- launching Claude/Gemini/Qwen in a terminal
+- listing existing terminal sessions
+- sending more input to an existing terminal
+- approving terminal prompts
+- closing a terminal session
+
+Do not use ACP for these unless the user explicitly asks for ACP/headless mode.
+
+### `V1DesktopRuntimeSessionsModule`
+
+```ts
+async openLauncher(body?: { workspaceSlug?: string; threadSlug?: string; presentationMode?: 'panel' | 'tab'; preferredAgentName?: string; preferredAgentProviderId?: string; }): Promise<unknown>
+async launchTerminalShell(body?: { workspaceSlug?: string; threadSlug?: string; presentationMode?: 'panel' | 'tab'; title?: string; subtitle?: string; initialCommand?: string; initialCommandMode?: 'direct' | 'prefill' | 'shell'; }): Promise<unknown>
+async launchTerminalCliAgent(body?: { workspaceSlug?: string; threadSlug?: string; agentName: string; providerId?: string; modelId?: string; presentationMode?: 'panel' | 'tab'; message?: string; }): Promise<unknown>
+async listRuntimeSessions(): Promise<unknown>
+async getRuntimeSession(sessionId: string): Promise<unknown>
+async write(sessionId: string, body?: { message?: string; input?: string; }): Promise<unknown>
+async permission(sessionId: string, body?: { outcome: 'approved' | 'denied'; actionId?: string; requestId?: string; optionId?: string; optionLabel?: string; input?: string; reason?: string; }): Promise<unknown>
+async deleteRuntimeSession(sessionId: string): Promise<unknown>
+```
+
+### Correct examples
+
+Launch Claude in a terminal:
+
+```js
+await sdk.desktopRuntimeSessions.launchTerminalCliAgent({
+  workspaceSlug: 'agent-heartbeat',
+  threadSlug: 'ambient-agent-week-agent-heartbeat-2026-w17',
+  agentName: 'claude',
+  providerId: 'claude-cli',
+  presentationMode: 'panel',
+  message: 'what is current working dir'
+});
+```
+
+Launch a shell and run `pwd`:
+
+```js
+await sdk.desktopRuntimeSessions.launchTerminalShell({
+  workspaceSlug: 'agent-heartbeat',
+  threadSlug: 'ambient-agent-week-agent-heartbeat-2026-w17',
+  presentationMode: 'panel',
+  initialCommand: 'pwd',
+  initialCommandMode: 'direct'
+});
+```
+
+Common mistake:
+
+```js
+// ❌ WRONG
+await sdk.desktopRuntimeSessions.launchTerminalCliAgent({
+  agentName: 'claude-cli'
+});
+
+// ✅ CORRECT
+await sdk.desktopRuntimeSessions.launchTerminalCliAgent({
+  agentName: 'claude',
+  providerId: 'claude-cli'
+});
+```
+
+Compatibility: `sdk.v1.desktopRuntimeSessions` remains available, but prefer the top-level alias.
+
+---
+
 ## Core — RealtimeXSDK
 
 ### `RealtimeXSDK`
@@ -52,6 +123,7 @@
 - `auth: AuthModule`
 - `credentials: CredentialsModule`
 - `v1: V1ApiNamespace | undefined`
+- `desktopRuntimeSessions: V1DesktopRuntimeSessionsModule | undefined`
 
 ```ts
 // Developer API (v1) — requires apiKey to be set in config.
@@ -503,7 +575,7 @@ outcome?: string
 
 ---
 
-## sdk.agent — Runtime Sessions (CLI Agent / Terminal mode)
+## sdk.agent — LLM Agent Sessions (REST/SSE)
 
 ### `AgentModule`
 
@@ -834,6 +906,38 @@ async deleteExposure(exposureId: string): Promise<unknown>
 
 ---
 
+## sdk.v1.desktopRuntimeSessions — v1 Desktop Runtime Sessions
+
+### `V1DesktopRuntimeSessionsModule`
+
+```ts
+// Open the shared terminal launcher in the Electron desktop app.
+async openLauncher(body?: Record<string, unknown>): Promise<unknown>
+
+// Launch a local PTY-backed shell terminal in the Electron desktop app.
+async launchTerminalShell(body?: Record<string, unknown>): Promise<unknown>
+
+// Launch a local PTY-backed CLI agent terminal in the Electron desktop app.
+async launchTerminalCliAgent(body?: Record<string, unknown>): Promise<unknown>
+
+// List desktop PTY-backed runtime sessions currently known to the Electron app.
+async listRuntimeSessions(): Promise<unknown>
+
+// Fetch one desktop PTY-backed runtime session by runtime session ID or PTY session ID.
+async getRuntimeSession(sessionId: string): Promise<unknown>
+
+// Close an existing desktop runtime session.
+async deleteRuntimeSession(sessionId: string): Promise<unknown>
+
+// Write input to an existing desktop runtime session. Use `message` to submit a CLI turn or `input` for raw PTY data.
+async write(sessionId: string, body?: Record<string, unknown>): Promise<unknown>
+
+// Approve or deny a pending desktop runtime session action.
+async permission(sessionId: string, body?: Record<string, unknown>): Promise<unknown>
+```
+
+---
+
 ## sdk.v1.document — v1 Document
 
 ### `V1DocumentModule`
@@ -918,38 +1022,6 @@ async listVectorStores(): Promise<unknown>
 
 ---
 
-## sdk.v1.runtimeSessions — Runtime Sessions (CLI Agent / Terminal mode)
-
-### `V1RuntimeSessionsModule`
-
-```ts
-// Resolve the desktop shell launch working directory for a workspace or thread context.
-async desktopShellLaunchSpec(body?: Record<string, unknown>): Promise<unknown>
-
-// Evaluate the runtime terminal permission policy for a pending CLI action.
-async terminalPermissionsEvaluate(body?: Record<string, unknown>): Promise<unknown>
-
-// Resolve the CLI agent terminal launch command and working directory.
-async cliAgentLaunchSpec(body?: Record<string, unknown>): Promise<unknown>
-
-// Create a persistent ACP-backed CLI agent runtime session.
-async cliAgent(body?: Record<string, unknown>): Promise<unknown>
-
-// Stream a chat turn to an existing CLI agent runtime session using Server-Sent Events.
-async cliAgentPermission(sessionKey: string, body?: Record<string, unknown>): Promise<unknown>
-
-// Cancel the current CLI turn for an active runtime session.
-async cliAgentCancel(sessionKey: string, body?: Record<string, unknown>): Promise<unknown>
-
-// Close a CLI agent runtime session and clear its control-plane metadata.
-async deleteCliAgent(sessionKey: string): Promise<unknown>
-
-// Fetch the current state and runtime options for a CLI agent session.
-async getCliAgent(sessionKey: string): Promise<unknown>
-```
-
----
-
 ## sdk.v1.sttApi — v1 Stt Api
 
 ### `V1SttApiModule`

package/skills/realtimex-moderator-sdk/references/known-issues.md

@@ -1,6 +1,6 @@
 # Known Issues — Source-Detected
 
-> Auto-generated by `scripts/generate-skill.mjs` · SDK **1.7.7** · 2026-05-05
+> Auto-generated by `scripts/generate-skill.mjs` · SDK **1.7.9** · 2026-05-06
 
 Run `node scripts/generate-skill.mjs --force` after SDK source changes to refresh.