Merge remote-tracking branch 'origin/master' into codex/status-bar-token-metrics

# Conflicts:
#	packages/client/ui-conversation/README.i18n.yaml
#	packages/host/apiproxy/README.i18n.yaml
#	packages/host/apiproxy/README.md
#	packages/host/apiproxy/README.zh.md
#	packages/host/apiproxy/src/api-proxy.ts

packages/host/apiproxy/src/api-proxy.ts

@@ -42,6 +42,7 @@ import type {
 import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction'
 import { pickNativeDirectory } from './native-directory-picker.ts'
 import { affectsSessionMetrics, SessionMetricsProjector } from './session-metrics.ts'
+import { openNativePath } from './native-path-opener.ts'
 
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
@@ -205,6 +206,8 @@ export interface ApiProxyDefaults {
   workspaceRoot: string
   /** Native single-directory picker; injectable for carrier tests. */
   pickDirectory?: (signal: AbortSignal) => Promise<string | null>
+  /** Native open-with-default-application; injectable for carrier tests. */
+  openPath?: (path: string, signal: AbortSignal) => Promise<void>
 }
 
 /** The tool/call payload fields the presenter path reads. */
@@ -1117,6 +1120,28 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           })
         }
       },
+
+      async openPath(request, signal) {
+        try {
+          const open = defaults.openPath
+            ?? ((path: string, openSignal: AbortSignal) => openNativePath(path, openSignal))
+          await open(request.payload.path, signal)
+          return ok(request, { opened: true as const })
+        } catch (error: unknown) {
+          if (signal.aborted) {
+            return err(request, {
+              code: 'cancelled',
+              message: 'path open was aborted',
+              details: {},
+            })
+          }
+          return err(request, {
+            code: 'internal',
+            message: `path open failed: ${error instanceof Error ? error.message : String(error)}`,
+            details: {},
+          })
+        }
+      },
     },
 
     commands: {

packages/host/apiproxy/src/api/host.schema.ts

@@ -25,3 +25,13 @@ export const hostPickDirectoryRequestSchema = z.object({}) satisfies z.ZodType<W
 export const hostPickDirectoryValueSchema = z.object({
   path: z.string().nullable(),
 }) satisfies z.ZodType<Wire<ResponseValue<'host.pickDirectory'>>>
+
+/** host.openPath request payload. */
+export const hostOpenPathRequestSchema = z.object({
+  path: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'host.openPath'>>>
+
+/** host.openPath response value. */
+export const hostOpenPathValueSchema = z.object({
+  opened: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.openPath'>>>

packages/host/apiproxy/src/api/host.ts

@@ -28,4 +28,14 @@ export interface HostApi {
     request: RpcRequest<{}>,
     signal: AbortSignal,
   ): Promise<RpcResponse<{ path: string | null }>>
+
+  /**
+   * Open a filesystem path with the operating system's default application
+   * (Finder / Explorer / xdg-open hand-off). The browser carrier restricts this
+   * privileged method to loopback, same-origin requests.
+   */
+  openPath(
+    request: RpcRequest<{ path: string }>,
+    signal: AbortSignal,
+  ): Promise<RpcResponse<{ opened: true }>>
 }

packages/host/apiproxy/src/api/rpc-map.ts

@@ -26,6 +26,7 @@ export interface RpcMethodMap {
   'session.cancel': SessionsApi['cancel']
   'host.describe': HostApi['describe']
   'host.pickDirectory': HostApi['pickDirectory']
+  'host.openPath': HostApi['openPath']
   'workspace.list': WorkspaceApi['list']
   'workspace.create': WorkspaceApi['create']
   'workspace.rename': WorkspaceApi['rename']

packages/host/apiproxy/src/fetch/client.ts

@@ -13,7 +13,9 @@ import { RpcId } from '../api/rpc.ts'
 import type { Wire } from '../api/rpc.schema.ts'
 import { rpcReceiptSchema, serverRequestSchema, serverResponseSchema } from '../api/rpc.schema.ts'
 import { hostFrameSchema, muxFrameSchema } from '../api/events.schema.ts'
-import { hostDescribeValueSchema, hostPickDirectoryValueSchema } from '../api/host.schema.ts'
+import {
+  hostDescribeValueSchema, hostOpenPathValueSchema, hostPickDirectoryValueSchema,
+} from '../api/host.schema.ts'
 import {
   sessionCancelValueSchema,
   sessionCreateValueSchema,
@@ -61,6 +63,7 @@ export interface IApiClient {
   host: {
     describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
     pickDirectory(payload: RequestPayload<'host.pickDirectory'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.pickDirectory'>>>
+    openPath(payload: RequestPayload<'host.openPath'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.openPath'>>>
   }
   workspace: {
     list(payload: RequestPayload<'workspace.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.list'>>>
@@ -98,6 +101,7 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'session.cancel': sessionCancelValueSchema,
   'host.describe': hostDescribeValueSchema,
   'host.pickDirectory': hostPickDirectoryValueSchema,
+  'host.openPath': hostOpenPathValueSchema,
   'workspace.list': workspaceListValueSchema,
   'workspace.create': workspaceCreateValueSchema,
   'workspace.rename': workspaceRenameValueSchema,
@@ -305,6 +309,7 @@ export abstract class AbstractApiClient implements IApiClient {
     // A native system dialog is user-paced and may legitimately stay open
     // longer than the normal unary deadline. Caller/connection aborts remain.
     pickDirectory: (payload, signal) => this.callUnary('host.pickDirectory', payload, signal, false),
+    openPath: (payload, signal) => this.callUnary('host.openPath', payload, signal),
   }
 
   readonly workspace: IApiClient['workspace'] = {

packages/host/apiproxy/src/fetch/handler.ts

@@ -23,7 +23,9 @@ import {
   sessionPromptRequestSchema,
   sessionSelectModelRequestSchema,
 } from '../api/sessions.schema.ts'
-import { hostDescribeRequestSchema, hostPickDirectoryRequestSchema } from '../api/host.schema.ts'
+import {
+  hostDescribeRequestSchema, hostOpenPathRequestSchema, hostPickDirectoryRequestSchema,
+} from '../api/host.schema.ts'
 import {
   workspaceCreateRequestSchema,
   workspaceDeleteRequestSchema,
@@ -60,6 +62,7 @@ const UNARY_ROUTES: UnaryRoutes = {
   'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
   'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
   'host.pickDirectory': { schema: hostPickDirectoryRequestSchema, invoke: (api, r, signal) => api.host.pickDirectory(r, signal) },
+  'host.openPath': { schema: hostOpenPathRequestSchema, invoke: (api, r, signal) => api.host.openPath(r, signal) },
   'workspace.list': { schema: workspaceListRequestSchema, invoke: (api, r) => api.workspace.list(r) },
   'workspace.create': { schema: workspaceCreateRequestSchema, invoke: (api, r) => api.workspace.create(r) },
   'workspace.rename': { schema: workspaceRenameRequestSchema, invoke: (api, r) => api.workspace.rename(r) },

packages/host/apiproxy/src/native-command.ts

@@ -0,0 +1,38 @@
+/** Shared no-shell `execFile` runner for native host dialogs and openers. */
+
+import { execFile } from 'node:child_process'
+
+/** Testable command boundary; native implementations never invoke a shell. */
+export type NativeCommandRunner = (
+  command: string,
+  args: readonly string[],
+  signal: AbortSignal,
+) => Promise<{ stdout: string; stderr: string }>
+
+/**
+ * Run a host command with utf8 stdio, abort propagation, and Windows hide.
+ * @param command - executable path or PATH name.
+ * @param args - argv (never a shell string).
+ * @param signal - caller/connection lifetime; abort terminates the child.
+ * @returns captured stdout/stderr on exit 0.
+ */
+export const runNativeCommand: NativeCommandRunner = (command, args, signal) =>
+  new Promise((resolve, reject) => {
+    execFile(
+      command,
+      [...args],
+      { encoding: 'utf8', signal, windowsHide: true },
+      (error, stdout, stderr) => {
+        if (error !== null) {
+          const failure = Object.assign(new Error(error.message, { cause: error }), {
+            code: error.code,
+            stdout,
+            stderr,
+          })
+          reject(failure)
+          return
+        }
+        resolve({ stdout, stderr })
+      },
+    )
+  })

packages/host/apiproxy/src/native-directory-picker.ts

@@ -1,13 +1,9 @@
 /** Cross-platform native single-directory picker used by the local GUI carrier. */
 
-import { execFile } from 'node:child_process'
+import { runNativeCommand, type NativeCommandRunner } from './native-command.ts'
 
 /** Testable command boundary; native implementations never invoke a shell. */
-export type DirectoryPickerRunner = (
-  command: string,
-  args: readonly string[],
-  signal: AbortSignal,
-) => Promise<{ stdout: string; stderr: string }>
+export type DirectoryPickerRunner = NativeCommandRunner
 
 /** Injectable platform facts for deterministic adapter tests. */
 export interface DirectoryPickerInternals {
@@ -15,27 +11,6 @@ export interface DirectoryPickerInternals {
   run?: DirectoryPickerRunner
 }
 
-const runCommand: DirectoryPickerRunner = (command, args, signal) =>
-  new Promise((resolve, reject) => {
-    execFile(
-      command,
-      [...args],
-      { encoding: 'utf8', signal, windowsHide: true },
-      (error, stdout, stderr) => {
-        if (error !== null) {
-          const failure = Object.assign(new Error(error.message, { cause: error }), {
-            code: error.code,
-            stdout,
-            stderr,
-          })
-          reject(failure)
-          return
-        }
-        resolve({ stdout, stderr })
-      },
-    )
-  })
-
 function outputPath(stdout: string): string | null {
   const path = stdout.replace(/[\r\n]+$/, '')
   return path === '' ? null : path
@@ -72,7 +47,7 @@ export async function pickNativeDirectory(
   internals: DirectoryPickerInternals = {},
 ): Promise<string | null> {
   const platform = internals.platform ?? process.platform
-  const run = internals.run ?? runCommand
+  const run = internals.run ?? runNativeCommand
 
   if (platform === 'darwin') {
     try {

packages/host/apiproxy/src/native-path-opener.ts

@@ -0,0 +1,53 @@
+/** Cross-platform open-with-default-application used by the local GUI carrier. */
+
+import { runNativeCommand, type NativeCommandRunner } from './native-command.ts'
+
+/** Testable command boundary; native implementations never invoke a shell. */
+export type PathOpenerRunner = NativeCommandRunner
+
+/** Injectable platform facts for deterministic adapter tests. */
+export interface PathOpenerInternals {
+  platform?: NodeJS.Platform
+  run?: PathOpenerRunner
+}
+
+/** PowerShell single-quoted literal (doubles embedded quotes). */
+function powershellLiteral(path: string): string {
+  return `'${path.replace(/'/g, "''")}'`
+}
+
+/**
+ * Open a filesystem path with the operating system's default application.
+ * @param path - absolute or host-resolvable path (caller owns resolution).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - platform and runner seam for deterministic tests.
+ */
+export async function openNativePath(
+  path: string,
+  signal: AbortSignal,
+  internals: PathOpenerInternals = {},
+): Promise<void> {
+  const platform = internals.platform ?? process.platform
+  const run = internals.run ?? runNativeCommand
+
+  if (platform === 'darwin') {
+    await run('open', [path], signal)
+    return
+  }
+
+  if (platform === 'win32') {
+    await run('powershell.exe', [
+      '-NoProfile',
+      '-Command',
+      `Invoke-Item -LiteralPath ${powershellLiteral(path)}`,
+    ], signal)
+    return
+  }
+
+  if (platform === 'linux') {
+    await run('xdg-open', [path], signal)
+    return
+  }
+
+  throw new Error(`native path opener is unsupported on ${platform}`)
+}