feat(web): open a produced file from the conversation

Serve one file at a time out of a Session's workspace under /f on the web
transport, and point the conversation's existing file-open affordance at it.
Clicking a write/edit/read row's path now opens that file in a browser tab —
including from a LAN client, where the Host's system opener is fenced to
loopback and answered nothing.

- /f/<sessionId>/<segments> in client-connection, behind the same
  browser-trust fence as /api; realpath confinement, streamed reads,
  GET/HEAD only, nosniff + no-store.
- Script-capable documents carry CSP sandbox: model-authored markup must not
  be same-origin with /api, where events.mux is a readable GET stream.
- ApiProxy.workspaceRootOf answers where a Session's files live without
  resuming an agent; the client program cannot reach the core services.
- The /f URL shape lives in dsh-host-apiproxy/api so both ends share one
  encoding (client bundles may not value-import another plugin).

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

@@ -0,0 +1,98 @@
+/**
+ * The `/f` workspace-file URL shape: the contract half of the web transport
+ * that carries bytes rather than RPC. The browser turns a tool's file path
+ * into a URL, the serving side turns that URL back into the segments below a
+ * session's cwd, and both read this one encoding decision so neither can drift
+ * into serving a path the other never meant. Pure string work with no Node and
+ * no DOM, like the rest of `api/` — the browser bundle inlines it.
+ * @module @deepseek-ai/dsh-host-apiproxy/api/files
+ */
+
+/**
+ * Route prefix owning every workspace-file read (`/f/<sessionId>/<segments…>`).
+ * The path carries the segments verbatim rather than a query parameter so a
+ * served document's relative references (`./logo.png`) resolve to their
+ * siblings in the same workspace directory.
+ */
+export const FILES_PATH = '/f'
+
+/** One parsed workspace-file request: whose workspace, and where inside it. */
+export interface WorkspaceFileTarget {
+  /** The owning session, still an opaque string — the caller resolves it to a cwd. */
+  sessionId: string
+  /** Decoded path segments below that session's cwd; never empty, never `.` or `..`. */
+  segments: string[]
+}
+
+/** A segment that survived decoding but would re-enter path resolution as more than one name. */
+function isPlainSegment(segment: string): boolean {
+  return segment !== '' && segment !== '.' && segment !== '..'
+    && !segment.includes('/') && !segment.includes('\\') && !segment.includes('\0')
+}
+
+function decode(raw: string): string | undefined {
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    // A malformed %-escape is a request we cannot interpret, not a miss.
+    return undefined
+  }
+}
+
+/**
+ * Express one tool-reported file path as segments below the session cwd.
+ * @param cwd - the session's working directory, or `undefined` when unknown.
+ * @param path - the path the tool reported (absolute, or relative to `cwd`).
+ * @returns the segments below `cwd`, or `undefined` when the path names
+ * something outside the workspace (which this route never serves) or resolves
+ * to the workspace directory itself.
+ */
+export function workspaceFileSegments(cwd: string | undefined, path: string): string[] | undefined {
+  const slashed = path.replace(/\\/g, '/')
+  const absolute = /^\/|^[A-Za-z]:\//.test(slashed)
+  let relative: string
+  if (absolute) {
+    if (cwd === undefined || cwd === '') return undefined
+    const root = cwd.replace(/\\/g, '/').replace(/\/+$/, '')
+    if (!slashed.startsWith(`${root}/`)) return undefined
+    relative = slashed.slice(root.length + 1)
+  } else {
+    relative = slashed
+  }
+  const segments = relative.split('/').filter(segment => segment !== '' && segment !== '.')
+  if (segments.length === 0 || segments.some(segment => !isPlainSegment(segment))) return undefined
+  return segments
+}
+
+/**
+ * Build the origin-relative URL serving one workspace file.
+ * @param sessionId - the session whose cwd anchors the path.
+ * @param segments - segments below that cwd, as {@link workspaceFileSegments} returns them.
+ * @returns the `/f/…` URL, resolved by the browser against the serving origin.
+ */
+export function workspaceFileUrl(sessionId: string, segments: readonly string[]): string {
+  const encoded = segments.map(segment => encodeURIComponent(segment)).join('/')
+  return `${FILES_PATH}/${encodeURIComponent(sessionId)}/${encoded}`
+}
+
+/**
+ * Parse a request pathname back into the session and segments it names.
+ * @param pathname - the request's raw (still percent-encoded) pathname.
+ * @returns the target, or `undefined` when the pathname is not a well-formed
+ * workspace-file read — including every traversal shape, which is refused here
+ * before any filesystem call rather than being resolved and then judged.
+ */
+export function parseWorkspaceFilePath(pathname: string): WorkspaceFileTarget | undefined {
+  if (!pathname.startsWith(`${FILES_PATH}/`)) return undefined
+  const [rawSession, ...rawSegments] = pathname.slice(FILES_PATH.length + 1).split('/')
+  if (rawSession === undefined || rawSegments.length === 0) return undefined
+  const sessionId = decode(rawSession)
+  if (sessionId === undefined || sessionId === '') return undefined
+  const segments: string[] = []
+  for (const raw of rawSegments) {
+    const segment = decode(raw)
+    if (segment === undefined || !isPlainSegment(segment)) return undefined
+    segments.push(segment)
+  }
+  return { sessionId, segments }
+}

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

@@ -15,6 +15,9 @@ import type { SettingsApi } from './settings.ts'
 import type { CredentialsApi } from './credentials.ts'
 import type { LlmApi } from './llm.ts'
 import type { ClientResponse, RpcReceipt } from './rpc.ts'
+// The merge-free types subpath: api/ is imported from the browser lane, where
+// the host session service must not merge over the client runtime's own.
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
 
 /** Root interface of the unified API surface. New client-request domain = one new file pair + one field here + one map row. */
 export interface ApiProxy {
@@ -30,6 +33,17 @@ export interface ApiProxy {
   llm: LlmApi
   /** Response entry for server-requests (client-response, echoing their rpcId); not a domain method (four-quadrant model). */
   respond(message: ClientResponse): Promise<RpcReceipt>
+  /**
+   * The directory a Session's files may be read from — the same `cwd` the
+   * session summaries carry, in non-envelope form for an in-process reader.
+   * Not a domain method: it has no wire face, because a browser learns a
+   * Session's cwd from `sessions.view` and a file it may read from the web
+   * transport's own `/f` route, never by asking for a host path.
+   * @param sessionId - the Session to locate.
+   * @returns its absolute working directory, or `undefined` when this host
+   * serves no such Session. Resolving one never resumes an agent.
+   */
+  workspaceRootOf(sessionId: SessionId): Promise<string | undefined>
 }
 
 // ---- Domain interfaces and payload entities ----
@@ -48,6 +62,10 @@ export type { SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSe
 export type { CredentialsApi, CredentialView } from './credentials.ts'
 export type { ConfigurableProviderView, LlmApi } from './llm.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'
+
+// ---- Workspace-file URL shape (the transport's byte-carrying half) ----
+export { FILES_PATH, workspaceFileSegments, workspaceFileUrl, parseWorkspaceFilePath } from './files.ts'
+export type { WorkspaceFileTarget } from './files.ts'
 export type { QuestionResponsePayload } from './questions.ts'
 
 // ---- Message layer: narrow forms (domain-signature view) ----