@realtimex/sdk 1.7.8 → 1.7.10

package/dist/{errors-BmVxnpJS.d.mts → errors-x6ngbrlA.d.mts}

@@ -498,4 +498,4 @@ declare class ServerError extends DeveloperApiError {
     constructor(message?: string);
 }
 
-export { AuthenticationError as A, DeveloperApiClient as D, NotFoundError as N, ServerError as S, V1ApiNamespace as V, DeveloperApiError as a, ValidationError as b, V1AuthModule as c, V1AdminModule as d, V1DocumentModule as e, V1WorkspaceModule as f, V1SystemModule as g, V1ThreadModule as h, V1UsersModule as i, V1OpenAIModule as j, V1EmbedModule as k, V1DesktopRuntimeSessionsModule as l };
+export { AuthenticationError as A, DeveloperApiClient as D, NotFoundError as N, ServerError as S, V1ApiNamespace as V, V1DesktopRuntimeSessionsModule as a, DeveloperApiError as b, ValidationError as c, V1AuthModule as d, V1AdminModule as e, V1DocumentModule as f, V1WorkspaceModule as g, V1SystemModule as h, V1ThreadModule as i, V1UsersModule as j, V1OpenAIModule as k, V1EmbedModule as l };

package/dist/{errors-BmVxnpJS.d.ts → errors-x6ngbrlA.d.ts}

@@ -498,4 +498,4 @@ declare class ServerError extends DeveloperApiError {
     constructor(message?: string);
 }
 
-export { AuthenticationError as A, DeveloperApiClient as D, NotFoundError as N, ServerError as S, V1ApiNamespace as V, DeveloperApiError as a, ValidationError as b, V1AuthModule as c, V1AdminModule as d, V1DocumentModule as e, V1WorkspaceModule as f, V1SystemModule as g, V1ThreadModule as h, V1UsersModule as i, V1OpenAIModule as j, V1EmbedModule as k, V1DesktopRuntimeSessionsModule as l };
+export { AuthenticationError as A, DeveloperApiClient as D, NotFoundError as N, ServerError as S, V1ApiNamespace as V, V1DesktopRuntimeSessionsModule as a, DeveloperApiError as b, ValidationError as c, V1AuthModule as d, V1AdminModule as e, V1DocumentModule as f, V1WorkspaceModule as g, V1SystemModule as h, V1ThreadModule as i, V1UsersModule as j, V1OpenAIModule as k, V1EmbedModule as l };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { V as V1ApiNamespace } from './errors-BmVxnpJS.mjs';
-export { A as AuthenticationError, D as DeveloperApiClient, a as DeveloperApiError, N as NotFoundError, S as ServerError, b as ValidationError } from './errors-BmVxnpJS.mjs';
+import { V as V1ApiNamespace, a as V1DesktopRuntimeSessionsModule } from './errors-x6ngbrlA.mjs';
+export { A as AuthenticationError, D as DeveloperApiClient, b as DeveloperApiError, N as NotFoundError, S as ServerError, c as ValidationError } from './errors-x6ngbrlA.mjs';
 
 /**
  * RealtimeX Local App SDK - Types
@@ -2022,6 +2022,11 @@ declare class RealtimeXSDK {
      * Provides access to workspace management, admin, documents, system settings, and more.
      */
     v1: V1ApiNamespace | undefined;
+    /**
+     * Desktop terminal sessions — top-level alias for the desktop runtime session APIs.
+     * Backed by `sdk.v1.desktopRuntimeSessions` for compatibility with generated v1 modules.
+     */
+    desktopRuntimeSessions: V1DesktopRuntimeSessionsModule | undefined;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { V as V1ApiNamespace } from './errors-BmVxnpJS.js';
-export { A as AuthenticationError, D as DeveloperApiClient, a as DeveloperApiError, N as NotFoundError, S as ServerError, b as ValidationError } from './errors-BmVxnpJS.js';
+import { V as V1ApiNamespace, a as V1DesktopRuntimeSessionsModule } from './errors-x6ngbrlA.js';
+export { A as AuthenticationError, D as DeveloperApiClient, b as DeveloperApiError, N as NotFoundError, S as ServerError, c as ValidationError } from './errors-x6ngbrlA.js';
 
 /**
  * RealtimeX Local App SDK - Types
@@ -2022,6 +2022,11 @@ declare class RealtimeXSDK {
      * Provides access to workspace management, admin, documents, system settings, and more.
      */
     v1: V1ApiNamespace | undefined;
+    /**
+     * Desktop terminal sessions — top-level alias for the desktop runtime session APIs.
+     * Backed by `sdk.v1.desktopRuntimeSessions` for compatibility with generated v1 modules.
+     */
+    desktopRuntimeSessions: V1DesktopRuntimeSessionsModule | undefined;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;

package/dist/index.js

@@ -4467,6 +4467,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.auth = new AuthModule(this.realtimexUrl, this.appId, this.apiKey);
     this.credentials = new CredentialsModule(this.httpClient);
     this.v1 = this.apiKey || this.appId ? new V1ApiNamespace(this.realtimexUrl, this.apiKey ?? "", this.appId || void 0) : void 0;
+    this.desktopRuntimeSessions = this.v1?.desktopRuntimeSessions;
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);

package/dist/index.mjs

@@ -3652,6 +3652,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.auth = new AuthModule(this.realtimexUrl, this.appId, this.apiKey);
     this.credentials = new CredentialsModule(this.httpClient);
     this.v1 = this.apiKey || this.appId ? new V1ApiNamespace(this.realtimexUrl, this.apiKey ?? "", this.appId || void 0) : void 0;
+    this.desktopRuntimeSessions = this.v1?.desktopRuntimeSessions;
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);

package/dist/v1/index.d.mts

@@ -1,5 +1,5 @@
-import { D as DeveloperApiClient } from '../errors-BmVxnpJS.mjs';
-export { A as AuthenticationError, a as DeveloperApiError, N as NotFoundError, S as ServerError, d as V1AdminModule, V as V1ApiNamespace, c as V1AuthModule, l as V1DesktopRuntimeSessionsModule, e as V1DocumentModule, k as V1EmbedModule, j as V1OpenAIModule, g as V1SystemModule, h as V1ThreadModule, i as V1UsersModule, f as V1WorkspaceModule, b as ValidationError } from '../errors-BmVxnpJS.mjs';
+import { D as DeveloperApiClient } from '../errors-x6ngbrlA.mjs';
+export { A as AuthenticationError, b as DeveloperApiError, N as NotFoundError, S as ServerError, e as V1AdminModule, V as V1ApiNamespace, d as V1AuthModule, a as V1DesktopRuntimeSessionsModule, f as V1DocumentModule, l as V1EmbedModule, k as V1OpenAIModule, h as V1SystemModule, i as V1ThreadModule, j as V1UsersModule, g as V1WorkspaceModule, c as ValidationError } from '../errors-x6ngbrlA.mjs';
 
 interface WorkspaceStreamChunk {
     /** The text fragment emitted by this SSE event */

package/dist/v1/index.d.ts

@@ -1,5 +1,5 @@
-import { D as DeveloperApiClient } from '../errors-BmVxnpJS.js';
-export { A as AuthenticationError, a as DeveloperApiError, N as NotFoundError, S as ServerError, d as V1AdminModule, V as V1ApiNamespace, c as V1AuthModule, l as V1DesktopRuntimeSessionsModule, e as V1DocumentModule, k as V1EmbedModule, j as V1OpenAIModule, g as V1SystemModule, h as V1ThreadModule, i as V1UsersModule, f as V1WorkspaceModule, b as ValidationError } from '../errors-BmVxnpJS.js';
+import { D as DeveloperApiClient } from '../errors-x6ngbrlA.js';
+export { A as AuthenticationError, b as DeveloperApiError, N as NotFoundError, S as ServerError, e as V1AdminModule, V as V1ApiNamespace, d as V1AuthModule, a as V1DesktopRuntimeSessionsModule, f as V1DocumentModule, l as V1EmbedModule, k as V1OpenAIModule, h as V1SystemModule, i as V1ThreadModule, j as V1UsersModule, g as V1WorkspaceModule, c as ValidationError } from '../errors-x6ngbrlA.js';
 
 interface WorkspaceStreamChunk {
     /** The text fragment emitted by this SSE event */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.7.8",
+    "version": "1.7.10",
     "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-06
-sdk_version: 1.7.8
+generated: 2026-05-07
+sdk_version: 1.7.10
 ---
 
 # RealTimeX Moderator (SDK Source-Verified)
 
-Interact with the RealTimeX platform (`http://localhost:3001`) using `@realtimex/sdk` **v1.7.8**. Authentication is automatic when running inside RealtimeX.
+Interact with the RealTimeX platform (`http://localhost:3001`) using `@realtimex/sdk` **v1.7.10**. 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
@@ -35,24 +39,115 @@ node "$SKILL" help
 
 ```js
 const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
-const { sdk } = await initSDK();
+const { sdk, context } = await initSDK();
 // All SDK APIs — see references/api-reference.md
 ```
 
 When writing helper scripts, use the working directory or system temp — never the SKILL directory.
 Scripts using the SDK must exit explicitly — `process.exit(0)` on success, `process.exit(1)` on error — or they hang on open HTTP sockets.
 
+When the skill runs inside a spawned ACP or desktop terminal session, RealtimeX injects:
+- `RTX_WORKSPACE_SLUG`
+- `RTX_THREAD_SLUG`
+
+The bundled `sdk-init` and `rtx.js` helpers use those env vars as default context for terminal actions and thread listing. Explicit arguments still win.
+
 ---
 
-## Runtime Sessions
+## Desktop Terminal Sessions
+
+For anything that says **launch terminal**, **open shell**, **open Claude/Gemini in terminal**, or **send another message to an existing terminal session**, use:
+
+- `sdk.desktopRuntimeSessions.*`
+
+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"
+});
+```
+
+If `workspaceSlug` and `threadSlug` are omitted, prefer this order:
+- explicit user-provided values
+- `RTX_WORKSPACE_SLUG` / `RTX_THREAD_SLUG` from the current spawned process
+- list workspaces/threads and ask only if still ambiguous
+
+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");
+```
 
-In this SDK, **Runtime Sessions** means the CLI Agent in **Terminal mode**. Use `sdk.agent.*` for that path.
+### Preferred decision rule
 
-This is separate from ACP mode:
-- `sdk.agent.*` = Runtime Sessions = CLI Agent / Terminal mode
-- `sdk.acpAgent.*` = ACP-backed CLI agent sessions
+If the user says:
+- "launch in terminal"
+- "open Claude in terminal"
+- "ask Gemini in terminal"
+- "open a shell and run pwd"
 
-If a user refers to the v1/OpenAPI tag `Runtime Sessions`, interpret that as the Terminal mode session flow, not ACP.
+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.8** · 2026-05-06
+> Auto-generated from `@realtimex/sdk` source · v**1.7.10** · 2026-05-07
 
 **Package:** `@realtimex/sdk` (CJS) · **Server:** `http://localhost:3001`
 **Developer Mode auth:** `Authorization: Bearer <apiKey>`
@@ -30,6 +30,78 @@
 
 ---
 
+## 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.
+If the current process was spawned by RealtimeX, prefer `process.env.RTX_WORKSPACE_SLUG` and `process.env.RTX_THREAD_SLUG` as default context before guessing or asking the user.
+
+### `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 +124,7 @@
 - `auth: AuthModule`
 - `credentials: CredentialsModule`
 - `v1: V1ApiNamespace | undefined`
+- `desktopRuntimeSessions: V1DesktopRuntimeSessionsModule | undefined`
 
 ```ts
 // Developer API (v1) — requires apiKey to be set in config.
@@ -503,7 +576,7 @@ outcome?: string
 
 ---
 
-## sdk.agent — Runtime Sessions (CLI Agent / Terminal mode)
+## sdk.agent — LLM Agent Sessions (REST/SSE)
 
 ### `AgentModule`
 

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.8** · 2026-05-06
+> Auto-generated by `scripts/generate-skill.mjs` · SDK **1.7.10** · 2026-05-07
 
 Run `node scripts/generate-skill.mjs --force` after SDK source changes to refresh.
 

package/skills/realtimex-moderator-sdk/scripts/lib/sdk-init.js

@@ -23,11 +23,17 @@ const ALL_PERMISSIONS = [
   'llm.chat', 'llm.embed', 'llm.providers',
   'vectors.read', 'vectors.write',
   'tts.generate', 'mcp.servers', 'mcp.tools', 'acp.agent',
+  'desktop.runtime-sessions',
 ];
 
 /** Well-known file written by RealtimeX server for seamless auth. */
 const SDK_APP_ID_FILE = path.join(os.homedir(), '.realtimex.ai', '.sdk-app-id');
 
+function normalizeContextValue(value) {
+  const normalized = String(value || '').trim();
+  return normalized || null;
+}
+
 function parseEnvFile(filePath) {
   const vars = {};
   if (!fs.existsSync(filePath)) return vars;
@@ -86,9 +92,24 @@ async function resolveCredentials({ envDir, apiKey, appId } = {}) {
   return { apiKey: null, appId: null };
 }
 
+function resolveDefaultWorkspaceThreadContext(overrides = {}) {
+  const workspaceSlug =
+    normalizeContextValue(overrides.workspaceSlug) ||
+    normalizeContextValue(process.env.RTX_WORKSPACE_SLUG);
+  const threadSlug =
+    normalizeContextValue(overrides.threadSlug) ||
+    normalizeContextValue(process.env.RTX_THREAD_SLUG);
+
+  return {
+    workspaceSlug,
+    threadSlug,
+  };
+}
+
 async function initSDK(opts = {}) {
   const { RealtimeXSDK } = require('@realtimex/sdk');
   const { apiKey, appId } = await resolveCredentials(opts);
+  const context = resolveDefaultWorkspaceThreadContext(opts);
 
   if (!apiKey && !appId) {
     throw new Error(
@@ -105,7 +126,14 @@ async function initSDK(opts = {}) {
     permissions: opts.permissions || ALL_PERMISSIONS,
   });
 
-  return { sdk, apiKey: apiKey || null, appId: appId || null };
+  return { sdk, apiKey: apiKey || null, appId: appId || null, context };
 }
 
-module.exports = { initSDK, resolveCredentials, parseEnvFile, ALL_PERMISSIONS, SDK_APP_ID_FILE };
+module.exports = {
+  initSDK,
+  resolveCredentials,
+  resolveDefaultWorkspaceThreadContext,
+  parseEnvFile,
+  ALL_PERMISSIONS,
+  SDK_APP_ID_FILE,
+};

package/skills/realtimex-moderator-sdk/scripts/rtx.js

@@ -53,6 +53,21 @@ async function getSDK() {
   return _sdk;
 }
 
+function applyWorkspaceThreadDefaults(body = {}, context = {}) {
+  const nextBody = { ...body };
+  if (!nextBody.workspaceSlug && context?.workspaceSlug) {
+    nextBody.workspaceSlug = context.workspaceSlug;
+  }
+  if (!nextBody.threadSlug && context?.threadSlug) {
+    nextBody.threadSlug = context.threadSlug;
+  }
+  return nextBody;
+}
+
+function resolveWorkspaceFlagOrContext(context = {}) {
+  return flags.workspace || context?.workspaceSlug || null;
+}
+
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -89,9 +104,10 @@ CMD.workspaces = async () => {
 // -- threads ----------------------------------------------------------------
 // Source: ApiModule.getThreads(workspaceSlug) → Thread[] { id, slug, name }
 CMD.threads = async () => {
-  const [slug] = cmdArgs;
+  const [slugArg] = cmdArgs;
+  const { sdk, context } = await getSDK();
+  const slug = slugArg || resolveWorkspaceFlagOrContext(context);
   if (!slug) { console.error('Usage: rtx.js threads <workspace-slug>'); process.exit(1); }
-  const { sdk } = await getSDK();
   printTable(await sdk.api.getThreads(slug), ['id', 'slug', 'name']);
 };
 
@@ -311,6 +327,116 @@ CMD['credentials'] = async () => {
   printTable(list, ['name', 'type']);
 };
 
+function getDesktopRuntimeSessionsModule(sdk) {
+  const module = sdk?.desktopRuntimeSessions || sdk?.v1?.desktopRuntimeSessions;
+  if (!module) {
+    throw new Error('sdk.desktopRuntimeSessions is unavailable. Ensure the SDK was initialized with Developer API access.');
+  }
+  return module;
+}
+
+// -- terminal-launcher / terminal sessions ----------------------------------
+CMD['terminal-open-launcher'] = async () => {
+  const { sdk, context } = await getSDK();
+  const terminal = getDesktopRuntimeSessionsModule(sdk);
+  const body = applyWorkspaceThreadDefaults({}, context);
+  if (flags.workspace) body.workspaceSlug = flags.workspace;
+  if (flags.thread) body.threadSlug = flags.thread;
+  if (flags.presentation) body.presentationMode = flags.presentation;
+  if (flags.agent) body.preferredAgentName = flags.agent;
+  if (flags.provider) body.preferredAgentProviderId = flags.provider;
+  print(await terminal.openLauncher(body));
+};
+
+CMD['terminal-launch-shell'] = async () => {
+  const { sdk, context } = await getSDK();
+  const terminal = getDesktopRuntimeSessionsModule(sdk);
+  const body = applyWorkspaceThreadDefaults({}, context);
+  if (flags.workspace) body.workspaceSlug = flags.workspace;
+  if (flags.thread) body.threadSlug = flags.thread;
+  if (flags.presentation) body.presentationMode = flags.presentation;
+  if (flags.command) body.initialCommand = flags.command;
+  if (flags['command-mode']) body.initialCommandMode = flags['command-mode'];
+  if (flags.title) body.title = flags.title;
+  if (flags.subtitle) body.subtitle = flags.subtitle;
+  print(await terminal.launchTerminalShell(body));
+};
+
+CMD['terminal-launch-cli-agent'] = async () => {
+  const [agentName, providerId, ...messageParts] = cmdArgs;
+  const message = messageParts.join(' ');
+  if (!agentName) {
+    console.error('Usage: rtx.js terminal-launch-cli-agent <agent-name> [<provider-id>] [<message>] [--workspace=<slug>] [--thread=<slug>] [--presentation=panel|tab] [--model=<id>]');
+    process.exit(1);
+  }
+  const { sdk, context } = await getSDK();
+  const terminal = getDesktopRuntimeSessionsModule(sdk);
+  const body = applyWorkspaceThreadDefaults({ agentName }, context);
+  if (providerId) body.providerId = providerId;
+  if (message) body.message = message;
+  if (flags.workspace) body.workspaceSlug = flags.workspace;
+  if (flags.thread) body.threadSlug = flags.thread;
+  if (flags.presentation) body.presentationMode = flags.presentation;
+  if (flags.model) body.modelId = flags.model;
+  print(await terminal.launchTerminalCliAgent(body));
+};
+
+CMD['terminal-sessions'] = async () => {
+  const { sdk } = await getSDK();
+  const terminal = getDesktopRuntimeSessionsModule(sdk);
+  const sessions = await terminal.listRuntimeSessions();
+  print(sessions);
+};
+
+CMD['terminal-session-get'] = async () => {
+  const [sessionId] = cmdArgs;
+  if (!sessionId) {
+    console.error('Usage: rtx.js terminal-session-get <session-id>');
+    process.exit(1);
+  }
+  const { sdk } = await getSDK();
+  const terminal = getDesktopRuntimeSessionsModule(sdk);
+  print(await terminal.getRuntimeSession(sessionId));
+};
+
+CMD['terminal-write'] = async () => {
+  const [sessionId, ...rest] = cmdArgs;
+  if (!sessionId || rest.length === 0) {
+    console.error('Usage: rtx.js terminal-write <session-id> <message> [--raw]');
+    process.exit(1);
+  }
+  const { sdk } = await getSDK();
+  const terminal = getDesktopRuntimeSessionsModule(sdk);
+  const payload = rest.join(' ');
+  print(await terminal.write(sessionId, flags.raw ? { input: payload } : { message: payload }));
+};
+
+CMD['terminal-permission'] = async () => {
+  const [sessionId, outcome, actionId] = cmdArgs;
+  if (!sessionId || !outcome) {
+    console.error('Usage: rtx.js terminal-permission <session-id> <approved|denied> [<action-id>] [--option-id=<id>] [--reason=<text>]');
+    process.exit(1);
+  }
+  const { sdk } = await getSDK();
+  const terminal = getDesktopRuntimeSessionsModule(sdk);
+  const body = { outcome };
+  if (actionId) body.actionId = actionId;
+  if (flags['option-id']) body.optionId = flags['option-id'];
+  if (flags.reason) body.reason = flags.reason;
+  print(await terminal.permission(sessionId, body));
+};
+
+CMD['terminal-close'] = async () => {
+  const [sessionId] = cmdArgs;
+  if (!sessionId) {
+    console.error('Usage: rtx.js terminal-close <session-id>');
+    process.exit(1);
+  }
+  const { sdk } = await getSDK();
+  const terminal = getDesktopRuntimeSessionsModule(sdk);
+  print(await terminal.deleteRuntimeSession(sessionId));
+};
+
 // -- acp-agents -------------------------------------------------------------
 // Source: AcpAgentModule.listAgents({ includeModels? })
 // Returns: AcpAgentInfo[] { id, label, handles[], installed, authReady, status }
@@ -808,6 +934,39 @@ sdk.credentials.*:
   credentials
     List available credentials (names and types, no values).
 
+sdk.desktopRuntimeSessions.* — Desktop terminal sessions:
+  terminal-open-launcher
+    [--workspace=<slug>] [--thread=<slug>] [--presentation=panel|tab]
+    Open the terminal launcher UI in the Electron app.
+
+  terminal-launch-shell
+    [--workspace=<slug>] [--thread=<slug>] [--presentation=panel|tab]
+    [--command="pwd"] [--command-mode=direct|prefill|shell]
+    Launch a visible shell terminal.
+
+  terminal-launch-cli-agent <agent-name> [<provider-id>] [<message>]
+    [--workspace=<slug>] [--thread=<slug>] [--presentation=panel|tab] [--model=<id>]
+    Launch a visible CLI agent terminal.
+    Example: terminal-launch-cli-agent claude claude-cli "what is current working dir"
+
+  terminal-sessions
+    List desktop terminal sessions.
+
+  terminal-session-get <session-id>
+    Fetch one desktop terminal session by runtime session id.
+
+  terminal-write <session-id> <message> [--raw]
+    Send another message or raw PTY input to an existing terminal session.
+
+  terminal-permission <session-id> <approved|denied> [<action-id>] [--option-id=<id>] [--reason=<text>]
+    Resolve a pending terminal approval request.
+
+  terminal-close <session-id>
+    Close a desktop terminal session.
+
+  Compatibility:
+    The SDK also exposes this module as sdk.v1.desktopRuntimeSessions.
+
 sdk.acpAgent.* — Session Management:
   acp-agents [--models=true]
     List available ACP CLI agents.