feat(agent-server): conversation-scoped runtime APIs and clients

.github/scripts/check_deprecations.py

@@ -299,6 +299,31 @@ def _gather_rest_route_deprecations(
     tree: ast.AST, path: Path, *, package: str
 ) -> Iterator[DeprecationRecord]:
     for node in ast.walk(tree):
+        if (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and node.func.attr == "add_api_route"
+            and isinstance(
+                deprecated_flag := _extract_kw(node, "deprecated"), ast.Constant
+            )
+            and deprecated_flag.value is True
+        ):
+            identifier = ast.unparse(node.args[0]) if node.args else "<route>"
+            deprecated_in, removed_in = _parse_rest_route_deprecation_docstring(
+                _extract_string_literal(_extract_kw(node, "description")),
+                path=path,
+                line=node.lineno,
+                route_identifiers=[identifier],
+            )
+            yield DeprecationRecord(
+                identifier=identifier,
+                removed_in=removed_in,
+                deprecated_in=deprecated_in,
+                path=path,
+                line=node.lineno,
+                kind="rest_route",
+                package=package,
+            )
         if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
             continue
 

.github/scripts/check_sdk_api_breakage.py

@@ -89,12 +89,20 @@ class FieldDefaultChange:
 DEPRECATION_RUNWAY_MINOR_RELEASES = 5
 FIELD_DEFAULT_CHANGE_REPORT_ENV = "SDK_API_BREAKAGE_REPORT_PATH"
 
-_ACCEPTED_REMOVED_MEMBERS: frozenset[tuple[str, str]] = frozenset(
-    {
-        ("openhands.workspace", "DockerDevWorkspace.mount_dir"),
-        ("openhands.workspace", "DockerWorkspace.mount_dir"),
-    }
-)
+_ACCEPTED_REMOVED_MEMBERS: dict[tuple[str, str], str] = {
+    ("openhands.workspace", "DockerDevWorkspace.mount_dir"): (
+        "Maintainers explicitly accepted this long-deprecated API break in "
+        "PR #3822, and that PR is labeled release-note-required."
+    ),
+    ("openhands.workspace", "DockerWorkspace.mount_dir"): (
+        "Maintainers explicitly accepted this long-deprecated API break in "
+        "PR #3822, and that PR is labeled release-note-required."
+    ),
+    ("openhands.sdk", "LLM.modify_params"): (
+        "Removed upstream in PR #4954 after its v1.42.0 to v1.47.0 "
+        "deprecation runway; legacy persisted settings are migrated on load."
+    ),
+}
 
 
 def _is_accepted_removed_member(package: str, feature: str) -> bool:
@@ -787,9 +795,8 @@ def _collect_breakages_pairs(
                             if emit_diagnostics:
                                 print(
                                     f"::notice title={title}::Accepted removal of "
-                                    f"{feature}. Maintainers explicitly accepted "
-                                    "this long-deprecated API break in PR #3822, "
-                                    "and that PR is labeled release-note-required."
+                                    f"{feature}. "
+                                    f"{_ACCEPTED_REMOVED_MEMBERS[package, feature]}"
                                 )
                             continue
 

.github/workflows/agent-server-rest-api-breakage.yml

@@ -5,7 +5,7 @@ on:
     push:
         branches: [main]
     pull_request:
-        branches: [main]
+        branches: [main, feat/conversation-scoped-runtime-api]
 
 jobs:
     agent-server-rest-api:

.github/workflows/api-breakage.yml

@@ -5,7 +5,7 @@ on:
     push:
         branches: [main]
     pull_request:
-        branches: [main]
+        branches: [main, feat/conversation-scoped-runtime-api]
 
 jobs:
     sdk-api:

.github/workflows/persisted-settings-compat.yml

@@ -5,7 +5,7 @@ on:
     push:
         branches: [main]
     pull_request:
-        branches: [main]
+        branches: [main, feat/conversation-scoped-runtime-api]
 
 jobs:
     persisted-settings-compat:

.github/workflows/review-thread-gate.yml

@@ -3,7 +3,7 @@ name: Review Thread Gate
 
 on:
     pull_request:
-        branches: [main]
+        branches: [main, feat/conversation-scoped-runtime-api]
         types: [opened, synchronize, reopened, ready_for_review, edited]
 
 permissions:

.github/workflows/server.yml

@@ -5,7 +5,7 @@ on:
     push:
         branches: [main]
     pull_request:
-        branches: [main]
+        branches: [main, feat/conversation-scoped-runtime-api]
     workflow_dispatch:
         inputs:
             base_image:

.github/workflows/typescript-client-ci.yml

@@ -5,7 +5,7 @@ on:
     push:
         branches: [main]
     pull_request:
-        branches: [main]
+        branches: [main, feat/conversation-scoped-runtime-api]
 
 defaults:
     run:

.github/workflows/typescript-client-integration-tests.yml

@@ -5,7 +5,7 @@ on:
     push:
         branches: [main]
     pull_request:
-        branches: [main]
+        branches: [main, feat/conversation-scoped-runtime-api]
     workflow_dispatch:
         inputs:
             llm_model:

.github/workflows/version-bump-guard.yml

@@ -3,7 +3,7 @@ name: Version bump guard
 
 on:
     pull_request:
-        branches: [main]
+        branches: [main, feat/conversation-scoped-runtime-api]
 
 jobs:
     version-bump-guard:

clients/typescript/src/__tests__/conversation-scope.test.ts

@@ -0,0 +1,71 @@
+import { createServer, Server } from 'node:http';
+import { AddressInfo } from 'node:net';
+import { ServerClient } from '../client/server-client';
+import { HttpClient } from '../client/http-client';
+import { RemoteWorkspace } from '../workspace/remote-workspace';
+
+describe('conversation-scoped requests', () => {
+  let server: Server;
+  let host: string;
+  const urls: string[] = [];
+  let scoped = false;
+  beforeAll(async () => {
+    server = createServer((req, res) => {
+      urls.push(req.url!);
+      if (req.url === '/server_info') {
+        res.setHeader('content-type', 'application/json');
+        res.end(JSON.stringify({ capabilities: scoped ? ['conversation_runtime_routes_v1'] : [] }));
+        return;
+      }
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ exit_code: 0, stdout: 'ok', stderr: '' }));
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    host = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+  });
+  afterAll(async () => {
+    server.closeAllConnections();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+  it('advertises client-side runtime routing support', () => {
+    expect(ServerClient.supportsConversationRuntimeRoutes).toBe(true);
+  });
+  it('scopes workspace commands to their conversation', async () => {
+    const workspace = new RemoteWorkspace({
+      host,
+      workingDir: '/workspace',
+      conversationId: 'demo-cid',
+    });
+    const result = await workspace.executeCommand('pwd');
+    expect(result.stdout).toBe('ok');
+    expect(urls.pop()).toBe('/api/bash/execute_bash_command?cid=demo-cid');
+  });
+  it('uses canonical routes and preserves explicit context on capable servers', async () => {
+    scoped = true;
+    try {
+      const client = new HttpClient({ baseUrl: host, conversationId: 'default' });
+      await client.get('/api/file/download', { params: { cid: 'explicit', path: '/workspace/a' } });
+      expect(urls.pop()).toBe('/api/conversations/explicit/file/download?path=%2Fworkspace%2Fa');
+      await client.post('/api/bash/execute_bash_command', { command: 'pwd' });
+      expect(urls.pop()).toBe('/api/conversations/default/bash/execute_bash_command');
+      await client.get('/api/tools/');
+      expect(urls.pop()).toBe('/api/tools/');
+      await client.get('/api/file/home');
+      expect(urls.pop()).toBe('/api/file/home');
+      await client.post('/api/mcp/test', { server: {} });
+      expect(urls.pop()).toBe('/api/conversations/default/mcp/test');
+      await client.get('/api/mcp/oauth/status/job');
+      expect(urls.pop()).toBe('/api/mcp/oauth/status/job');
+    } finally {
+      scoped = false;
+    }
+  });
+  it('preserves unscoped behavior and explicit query context', async () => {
+    await new HttpClient({ baseUrl: host }).get('/api/file/home');
+    expect(urls.pop()).toBe('/api/file/home');
+    await new HttpClient({ baseUrl: host, conversationId: 'default' }).get('/api/file/download', {
+      params: { cid: 'explicit' },
+    });
+    expect(urls.pop()).toBe('/api/file/download?cid=explicit');
+  });
+});

clients/typescript/src/client/bash-client.ts

@@ -11,6 +11,7 @@ import {
 
 export interface BashClientOptions {
   host: string;
+  conversationId?: string;
   apiKey?: string;
   timeout?: number;
 }
@@ -25,6 +26,7 @@ export class BashClient {
     this.apiKey = options.apiKey;
     this.client = new HttpClient({
       baseUrl: this.host,
+      conversationId: options.conversationId,
       apiKey: this.apiKey,
       timeout: options.timeout || 60000,
     });

clients/typescript/src/client/desktop-client.ts

@@ -3,6 +3,7 @@ import { DesktopUrlResponse } from '../models/api';
 
 export interface DesktopClientOptions {
   host: string;
+  conversationId?: string;
   apiKey?: string;
   timeout?: number;
 }
@@ -17,6 +18,7 @@ export class DesktopClient {
     this.apiKey = options.apiKey;
     this.client = new HttpClient({
       baseUrl: this.host,
+      conversationId: options.conversationId,
       apiKey: this.apiKey,
       timeout: options.timeout || 60000,
     });

clients/typescript/src/client/file-client.ts

@@ -9,6 +9,7 @@ import type { Success } from '../types/base';
 
 export interface FileClientOptions {
   host: string;
+  conversationId?: string;
   apiKey?: string;
   timeout?: number;
 }
@@ -25,6 +26,7 @@ export class FileClient {
     this.apiKey = options.apiKey;
     this.client = new HttpClient({
       baseUrl: this.host,
+      conversationId: options.conversationId,
       apiKey: this.apiKey,
       timeout: options.timeout || 60000,
     });

clients/typescript/src/client/http-client.ts

@@ -4,6 +4,7 @@
 
 export interface HttpClientOptions {
   baseUrl: string;
+  conversationId?: string;
   apiKey?: string;
   timeout?: number;
 }
@@ -48,16 +49,25 @@ export class HttpError extends Error {
 }
 
 export class HttpClient {
+  private conversationId?: string;
   private baseUrl: string;
   private apiKey?: string;
   private timeout: number;
+  private runtimeRoutes?: Promise<boolean>;
 
   constructor(options: HttpClientOptions) {
     this.baseUrl = options.baseUrl.replace(/\/$/, '');
     this.apiKey = options.apiKey;
+    this.conversationId = options.conversationId;
     this.timeout = options.timeout || 60000;
   }
 
+  private isRuntimePath(path: string): boolean {
+    if (path === '/api/mcp/test') return true;
+    if (path === '/api/file/home' || path === '/api/file/search_subdirs') return false;
+    return /^\/api\/(bash|file|git|desktop|vscode)(\/|$)/.test(path);
+  }
+
   private buildUrl(path: string, params?: Record<string, unknown>): URL {
     const relativePath = path.startsWith('/') ? path.slice(1) : path;
     const url = new URL(relativePath, this.baseUrl + '/');
@@ -74,10 +84,29 @@ export class HttpClient {
       });
     }
 
+    if (this.conversationId && this.isRuntimePath(path) && !url.searchParams.has('cid')) {
+      url.searchParams.set('cid', this.conversationId);
+    }
     return url;
   }
 
   async request<T = unknown>(options: RequestOptions): Promise<HttpResponse<T>> {
+    if (this.conversationId && this.isRuntimePath(options.url)) {
+      this.runtimeRoutes ??= this.get<{ capabilities?: string[] }>('/server_info')
+        .then(({ data }) => data.capabilities?.includes('conversation_runtime_routes_v1') ?? false)
+        .catch((error: unknown) => {
+          if (error instanceof HttpError && error.status === 404) return false;
+          this.runtimeRoutes = undefined;
+          throw error;
+        });
+      if (await this.runtimeRoutes) {
+        options = {
+          ...options,
+          url: `/api/conversations/${encodeURIComponent(String(options.params?.cid ?? this.conversationId))}${options.url.slice(4)}`,
+          params: { ...options.params, cid: undefined },
+        };
+      }
+    }
     // `fetch` (and browsers) reject a body on a GET request, but a few
     // agent-server batch endpoints (e.g. `GET /api/bash/bash_events/` and
     // `GET /api/conversations/{id}/events`) are declared as GET-with-required-body.

clients/typescript/src/client/mcp-client.ts

@@ -20,6 +20,7 @@ import type {
 
 export interface MCPClientOptions {
   host: string;
+  conversationId?: string;
   apiKey?: string;
   timeout?: number;
 }
@@ -34,6 +35,7 @@ export class MCPClient {
     this.apiKey = options.apiKey;
     this.client = new HttpClient({
       baseUrl: this.host,
+      conversationId: options.conversationId,
       apiKey: this.apiKey,
       timeout: options.timeout || 60000,
     });

clients/typescript/src/client/server-client.ts

@@ -9,6 +9,7 @@ export interface ServerClientOptions {
 }
 
 export class ServerClient {
+  public static readonly supportsConversationRuntimeRoutes = true;
   public readonly host: string;
   public readonly apiKey?: string;
   private readonly client: HttpClient;

clients/typescript/src/client/vscode-client.ts

@@ -3,6 +3,7 @@ import { VSCodeStatusResponse, VSCodeUrlResponse } from '../models/api';
 
 export interface VSCodeClientOptions {
   host: string;
+  conversationId?: string;
   apiKey?: string;
   timeout?: number;
 }
@@ -22,6 +23,7 @@ export class VSCodeClient {
     this.apiKey = options.apiKey;
     this.client = new HttpClient({
       baseUrl: this.host,
+      conversationId: options.conversationId,
       apiKey: this.apiKey,
       timeout: options.timeout || 60000,
     });

clients/typescript/src/models/agent-server-api.ts

@@ -29,7 +29,11 @@ export type AgentServerSettingsPatchRequest = UpdateSettingsApiSettingsPatchData
 export type AgentServerSettingsPatchResponse = UpdateSettingsApiSettingsPatchResponse;
 
 export type AgentServerMCPTestRequest = TestMcpServerApiMcpTestPostData['body'];
-export type AgentServerMCPTestResponse = TestMcpServerApiMcpTestPostResponse;
+export type AgentServerMCPTestResponse = TestMcpServerApiMcpTestPostResponse & {
+  /** Absent on older servers. Host success does not verify a conversation runtime. */
+  scope?: 'host' | 'runtime';
+  runtime_verified?: boolean;
+};
 export type AgentServerMCPToolCall = McpToolCallSpec;
 export type AgentServerMCPStartOAuthRequest = StartMcpOauthApiMcpOauthStartPostData['body'];
 export type AgentServerMCPStartOAuthResponse = StartMcpOauthApiMcpOauthStartPostResponse;

clients/typescript/src/models/api.ts

@@ -592,6 +592,8 @@ export interface MCPToolCallResult {
 }
 
 export interface MCPTestSuccess {
+  scope?: 'host' | 'runtime';
+  runtime_verified?: boolean;
   ok: true;
   tools: string[];
   tool_result?: MCPToolCallResult | null;
@@ -602,6 +604,8 @@ export interface MCPTestSuccess {
 export type MCPTestFailureKind = 'timeout' | 'connection' | 'unknown';
 
 export interface MCPTestFailure {
+  scope?: 'host' | 'runtime';
+  runtime_verified?: boolean;
   ok: false;
   error: string;
   error_kind: MCPTestFailureKind;