refactor(agent-presets,web): copy-only preset authoring with a path to the files

The web YAML editor is gone. agentPreset.write (arbitrary composition
text) became agentPreset.copy { from, agentPreset, name? }: a host-side
whole-directory copy of ids the host resolves itself — symlinks
dereferenced, modes re-tightened to owner-only with owner-execute kept,
metadata rewritten to keep the source's description but never its name or
roster order. No composition text or path crosses the wire in either
authoring direction, and the entryListSchema/!!js concern dissolves with
assertComposition itself.

The settings section becomes: a read-only viewer over shipped
compositions, a copy dialog (id + optional display name) as the only
create entry, delete for custom rows, and a location action leading into
the preset's own files — agentPreset.openDocument { agentPreset } resolves
the directory host-side and opens it natively, or answers
{ opened: false, path } for the row to show as text where the deployment
has no desktop. agentPreset.list reports hasDocument beside authorable;
the gateway's nativeOpen config pins the capability where
canOpenNativePath platform detection would mislead. The privileged set is
now read/copy/openDocument/remove.

With files as the only composition editor, standing mounts grew
stamp-keyed generations: ensureStanding compares the composition file's
mtime+size and starts the next generation for later sessions, while every
joined session keeps the generation it runs on.

New keyless web lane (agent-preset-authoring, overlay pins
nativeOpen: false so goldens render one branch on every platform) drives
view/copy/reveal/delete end to end; the real-composition CLI e2e switches
to copy semantics.

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

@@ -5,7 +5,7 @@
 
 import { randomUUID } from 'node:crypto'
 import { mkdir, stat } from 'node:fs/promises'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import type { Context } from 'cordis'
 import { installAgentLlmTarget } from '@deepseek-ai/dsh-agent'
 import type { Agent, AgentLlmTarget, AgentLlmTargetRef, AgentOptions, AgentStatus } from '@deepseek-ai/dsh-agent'
@@ -25,7 +25,7 @@ import {
 } from '@deepseek-ai/dsh-workspace'
 // Type-only: brings the `ctx.tools` Context merge into this program (viewFor reads presenters).
 import {
-  InvalidCompositionError, InvalidPresetIdError, PresetMountError,
+  InvalidPresetIdError, PresetExistsError, PresetMountError,
   PresetNotWritableError, resolveSessionPreset,
   SETTINGS_NAMESPACE as AGENT_PRESET_SETTINGS_NAMESPACE, UnknownPresetError,
 } from '@deepseek-ai/dsh-agent-presets'
@@ -83,7 +83,7 @@ import {
   hasApiRemoteSubagentOwner,
   inspectApiRemoteSession,
 } from '@deepseek-ai/dsh-api-remotes'
-import { openNativePath, openNativeTextFile } from './native-path-opener.ts'
+import { canOpenNativePath, openNativePath, openNativeTextFile } from './native-path-opener.ts'
 
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
@@ -415,6 +415,14 @@ export interface ApiProxyDefaults {
   openPath?: (path: string, signal: AbortSignal) => Promise<void>
   /** Native text-editor handoff; injectable for settings-document tests. */
   openTextFile?: (path: string, signal: AbortSignal) => Promise<void>
+  /**
+   * Whether handing a path to the native opener can work at all — the
+   * `hasDocument` capability the preset roster reports, and the switch
+   * between opening a preset directory and answering its path as text.
+   * Absent, an injected `openPath` counts as openable and everything else
+   * falls back to platform detection ({@link canOpenNativePath}).
+   */
+  canOpenPath?: () => boolean
 }
 
 /** The tool/call payload fields the presenter path reads. */
@@ -757,7 +765,7 @@ function presetError(agentPreset: string, error: unknown): RpcError {
   if (error instanceof PresetNotWritableError) {
     return { code: 'agent-preset-read-only', message: error.message, details: { agentPreset, reason: error.message } }
   }
-  if (error instanceof InvalidPresetIdError || error instanceof InvalidCompositionError) {
+  if (error instanceof InvalidPresetIdError || error instanceof PresetExistsError) {
     return { code: 'agent-preset-invalid', message: error.message, details: { agentPreset, reason: error.message } }
   }
   return { code: 'internal', message: `agent preset "${agentPreset}": ${String(error)}`, details: {} }
@@ -1543,6 +1551,13 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     return openTarget(request, path, signal, open)
   }
 
+  /** Whether this deployment can hand a path to a native opener at all. */
+  function canOpenPaths(): boolean {
+    if (defaults.canOpenPath !== undefined) return defaults.canOpenPath()
+    // An injected opener is by definition usable; otherwise ask the platform.
+    return defaults.openPath !== undefined || canOpenNativePath()
+  }
+
   /** Missing-service report shared by the credentials domain. */
   function credentialsAbsent(): RpcError {
     return { code: 'internal', message: 'credentials service is absent: this deployment does not mount a credential provider (e.g. @deepseek-ai/dsh-credentials-local) in its composition', details: {} }
@@ -2614,7 +2629,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       // simply offers no choice.
       async list(request) {
         const presets = ctx.get('agentPresets')
-        if (presets === undefined) return ok(request, { presets: [], authorable: false })
+        if (presets === undefined) return ok(request, { presets: [], authorable: false, hasDocument: false })
         const defaultId = presets.defaultId
         return ok(request, {
           presets: (await presets.list()).map(preset => ({
@@ -2625,6 +2640,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             ...preset.description === undefined ? {} : { description: preset.description },
           })),
           authorable: presets.authorable,
+          hasDocument: canOpenPaths(),
         })
       },
 
@@ -2682,7 +2698,8 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
 
       // Authoring is privileged (see PRIVILEGED_METHODS in dsh-client-connection):
       // a composition names the plugins a session runs, so reading one is
-      // reconnaissance and writing one is arbitrary capability.
+      // reconnaissance, and copy/remove/openDocument manage the roster and
+      // drive the host desktop.
       async read(request) {
         const { agentPreset } = request.payload
         const presets = ctx.get('agentPresets')
@@ -2693,7 +2710,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             agentPreset: preset.id,
             trust: preset.trust,
             content: await presets.read(preset.id),
-            writable: preset.trust === 'user' && presets.authorable,
             ...preset.name === undefined ? {} : { name: preset.name },
             ...preset.description === undefined ? {} : { description: preset.description },
           })
@@ -2702,21 +2718,41 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         }
       },
 
-      async write(request) {
-        const { agentPreset, content, name, description } = request.payload
+      async copy(request) {
+        const { from, agentPreset, name } = request.payload
         const presets = ctx.get('agentPresets')
         if (presets === undefined) return err(request, noRoster(agentPreset))
         try {
-          await presets.write(agentPreset, content, {
-            ...name === undefined ? {} : { name },
-            ...description === undefined ? {} : { description },
-          })
+          await presets.copy(from, agentPreset, name)
           return ok(request, { agentPreset })
         } catch (error: unknown) {
           return err(request, presetError(agentPreset, error))
         }
       },
 
+      async openDocument(request, signal) {
+        const { agentPreset } = request.payload
+        const presets = ctx.get('agentPresets')
+        if (presets === undefined) return err(request, noRoster(agentPreset))
+        try {
+          const preset = await presets.resolve(agentPreset)
+          // Same line as copy/remove draw: the shipped install is not the
+          // user's to manage, and pointing an editor into it invites edits an
+          // upgrade will silently overwrite.
+          if (preset.trust !== 'user') {
+            throw new PresetNotWritableError(preset.id, 'it ships with the deployment')
+          }
+          // The id resolved against the Host's own roots is what selects the
+          // directory — no browser payload carries a path in either direction
+          // unless the deployment has no opener to hand it to.
+          const directory = dirname(preset.path)
+          if (!canOpenPaths()) return ok(request, { opened: false as const, path: directory })
+          return await openPath(request, directory, signal)
+        } catch (error: unknown) {
+          return err(request, presetError(agentPreset, error))
+        }
+      },
+
       async remove(request) {
         const { agentPreset } = request.payload
         const presets = ctx.get('agentPresets')

packages/host/apiproxy/src/api/agent-presets.schema.ts

@@ -26,6 +26,7 @@ export const agentPresetListRequestSchema = z.object({
 export const agentPresetListValueSchema = z.object({
   presets: z.array(agentPresetEntrySchema),
   authorable: z.boolean(),
+  hasDocument: z.boolean(),
 }) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.list'>>>
 
 /** agentPreset.select request payload. */
@@ -49,23 +50,32 @@ export const agentPresetReadValueSchema = z.object({
   agentPreset: z.string(),
   trust: z.union([z.literal('system'), z.literal('user')]),
   content: z.string(),
-  writable: z.boolean(),
   name: z.string().optional(),
   description: z.string().optional(),
 }) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.read'>>>
 
-/** agentPreset.write request payload. */
-export const agentPresetWriteRequestSchema = z.object({
+/** agentPreset.copy request payload. */
+export const agentPresetCopyRequestSchema = z.object({
+  from: z.string().min(1),
   agentPreset: z.string().min(1),
-  content: z.string(),
   name: z.string().optional(),
-  description: z.string().optional(),
-}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.write'>>>
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.copy'>>>
 
-/** agentPreset.write response value. */
-export const agentPresetWriteValueSchema = z.object({
+/** agentPreset.copy response value. */
+export const agentPresetCopyValueSchema = z.object({
   agentPreset: z.string(),
-}) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.write'>>>
+}) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.copy'>>>
+
+/** agentPreset.openDocument request payload. */
+export const agentPresetOpenDocumentRequestSchema = z.object({
+  agentPreset: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.openDocument'>>>
+
+/** agentPreset.openDocument response value. */
+export const agentPresetOpenDocumentValueSchema = z.union([
+  z.object({ opened: z.literal(true) }),
+  z.object({ opened: z.literal(false), path: z.string() }),
+]) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.openDocument'>>>
 
 /** agentPreset.remove request payload. */
 export const agentPresetRemoveRequestSchema = z.object({

packages/host/apiproxy/src/api/agent-presets.ts

@@ -3,10 +3,10 @@
  * session, plus the authoring calls behind it.
  *
  * `list` is ordinary: it carries ids and trust, and every preset picker needs
- * it. Everything else is privileged and loopback-pinned — a composition names
- * the plugins a session runs, so reading one is reconnaissance, writing one is
- * arbitrary capability, and selecting one can move a session onto a preset
- * that edits the live runtime.
+ * it. The authoring calls are privileged and loopback-pinned — a composition
+ * names the plugins a session runs, so reading one is reconnaissance, and
+ * although authoring is copy-only (no caller supplies composition text or a
+ * path), copying and deleting still rearrange what the deployment offers.
  */
 
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -45,11 +45,13 @@ export interface AgentPresetsApi {
    * shipped ids.
    * An empty roster means the deployment composes no presets at all, and
    * every session shares the host composition. `authorable` reports whether
-   * the deployment configures a root new presets can be written to, which is
-   * a deployment fact rather than a per-preset one.
+   * the deployment configures a root new presets can be written to, and
+   * `hasDocument` whether `openDocument` can hand a preset directory to a
+   * native opener — both deployment facts rather than per-preset ones, and
+   * neither exposes a Host path.
    */
   list(request: RpcRequest<{}>):
-  Promise<RpcResponse<{ presets: readonly AgentPresetEntry[]; authorable: boolean }>>
+  Promise<RpcResponse<{ presets: readonly AgentPresetEntry[]; authorable: boolean; hasDocument: boolean }>>
 
   /**
    * Recompose one session's agent from a different preset.
@@ -63,29 +65,45 @@ export interface AgentPresetsApi {
   Promise<RpcResponse<{ agentPreset: string }>>
 
   /**
-   * Read one preset's composition text, for an editor.
+   * Read one preset's composition text, for the read-only viewer.
    *
-   * Privileged: a composition names the plugins a session runs, so reading one
-   * is reconnaissance and writing one is arbitrary capability.
+   * Privileged: a composition names the plugins a session runs, so reading
+   * one is reconnaissance.
    */
   read(request: RpcRequest<{ agentPreset: string }>):
   Promise<RpcResponse<{
     agentPreset: string
     trust: 'system' | 'user'
     content: string
-    writable: boolean
     name?: string
     description?: string
   }>>
 
   /**
-   * Create or replace a locally authored preset. Shipped presets are refused;
-   * the text is shape-checked before it lands, so a save cannot leave a file no
-   * session could load.
+   * Create a locally authored preset by copying an existing one whole.
+   *
+   * The only authoring write. No composition text and no path crosses the
+   * wire: `from` and `agentPreset` are ids the Host resolves against its own
+   * roots, so a copy is exactly as loadable as its source and grants nothing
+   * the roster did not already carry. The copy keeps the source's description
+   * (the file is the author's to edit afterwards) but not its name — `name`
+   * here or the id fallback is what distinguishes the rows.
    */
-  write(request: RpcRequest<{ agentPreset: string; content: string; name?: string; description?: string }>):
+  copy(request: RpcRequest<{ from: string; agentPreset: string; name?: string }>):
   Promise<RpcResponse<{ agentPreset: string }>>
 
+  /**
+   * Hand one locally authored preset's DIRECTORY to the platform opener, for
+   * editing the files that are now the only composition editor. The request
+   * carries an id, never a path — the Host resolves it — so no browser
+   * payload can select an arbitrary filesystem target. Where the deployment
+   * has no native opener (`hasDocument: false` on `list`), the reply carries
+   * the resolved directory for the surface to show as text instead. Shipped
+   * presets are refused: their install is not the user's to manage.
+   */
+  openDocument(request: RpcRequest<{ agentPreset: string }>, signal: AbortSignal):
+  Promise<RpcResponse<{ opened: true } | { opened: false; path: string }>>
+
   /** Delete a locally authored preset. Shipped presets are refused. */
   remove(request: RpcRequest<{ agentPreset: string }>): Promise<RpcResponse<{}>>
 }

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

@@ -54,7 +54,8 @@ export interface RpcMethodMap {
   'agentPreset.list': AgentPresetsApi['list']
   'agentPreset.select': AgentPresetsApi['select']
   'agentPreset.read': AgentPresetsApi['read']
-  'agentPreset.write': AgentPresetsApi['write']
+  'agentPreset.copy': AgentPresetsApi['copy']
+  'agentPreset.openDocument': AgentPresetsApi['openDocument']
   'agentPreset.remove': AgentPresetsApi['remove']
   'goal.create': GoalsApi['create']
   'goal.edit': GoalsApi['edit']

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

@@ -41,8 +41,8 @@ import {
 import { commandExecuteValueSchema, commandListValueSchema } from '../api/commands.schema.ts'
 import { skillListValueSchema } from '../api/skills.schema.ts'
 import {
-  agentPresetListValueSchema, agentPresetReadValueSchema, agentPresetRemoveValueSchema,
-  agentPresetSelectValueSchema, agentPresetWriteValueSchema,
+  agentPresetCopyValueSchema, agentPresetListValueSchema, agentPresetOpenDocumentValueSchema,
+  agentPresetReadValueSchema, agentPresetRemoveValueSchema, agentPresetSelectValueSchema,
 } from '../api/agent-presets.schema.ts'
 import {
   goalCreateValueSchema,
@@ -127,7 +127,8 @@ export interface IApiClient {
     list(payload: RequestPayload<'agentPreset.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.list'>>>
     select(payload: RequestPayload<'agentPreset.select'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.select'>>>
     read(payload: RequestPayload<'agentPreset.read'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.read'>>>
-    write(payload: RequestPayload<'agentPreset.write'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.write'>>>
+    copy(payload: RequestPayload<'agentPreset.copy'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.copy'>>>
+    openDocument(payload: RequestPayload<'agentPreset.openDocument'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.openDocument'>>>
     remove(payload: RequestPayload<'agentPreset.remove'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.remove'>>>
   }
   events: {
@@ -199,7 +200,8 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'agentPreset.list': agentPresetListValueSchema,
   'agentPreset.select': agentPresetSelectValueSchema,
   'agentPreset.read': agentPresetReadValueSchema,
-  'agentPreset.write': agentPresetWriteValueSchema,
+  'agentPreset.copy': agentPresetCopyValueSchema,
+  'agentPreset.openDocument': agentPresetOpenDocumentValueSchema,
   'agentPreset.remove': agentPresetRemoveValueSchema,
   'goal.create': goalCreateValueSchema,
   'goal.edit': goalEditValueSchema,
@@ -468,7 +470,8 @@ export abstract class AbstractApiClient implements IApiClient {
     list: (payload, signal) => this.callUnary('agentPreset.list', payload, signal),
     select: (payload, signal) => this.callUnary('agentPreset.select', payload, signal),
     read: (payload, signal) => this.callUnary('agentPreset.read', payload, signal),
-    write: (payload, signal) => this.callUnary('agentPreset.write', payload, signal),
+    copy: (payload, signal) => this.callUnary('agentPreset.copy', payload, signal),
+    openDocument: (payload, signal) => this.callUnary('agentPreset.openDocument', payload, signal),
     remove: (payload, signal) => this.callUnary('agentPreset.remove', payload, signal),
   }
 

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

@@ -43,8 +43,8 @@ import {
 import { commandExecuteRequestSchema, commandListRequestSchema } from '../api/commands.schema.ts'
 import { skillListRequestSchema } from '../api/skills.schema.ts'
 import {
-  agentPresetListRequestSchema, agentPresetReadRequestSchema, agentPresetRemoveRequestSchema,
-  agentPresetSelectRequestSchema, agentPresetWriteRequestSchema,
+  agentPresetCopyRequestSchema, agentPresetListRequestSchema, agentPresetOpenDocumentRequestSchema,
+  agentPresetReadRequestSchema, agentPresetRemoveRequestSchema, agentPresetSelectRequestSchema,
 } from '../api/agent-presets.schema.ts'
 import {
   goalCreateRequestSchema,
@@ -116,7 +116,8 @@ const UNARY_ROUTES: UnaryRoutes = {
   'agentPreset.list': { schema: agentPresetListRequestSchema, invoke: (api, r) => api.agentPresets.list(r) },
   'agentPreset.select': { schema: agentPresetSelectRequestSchema, invoke: (api, r) => api.agentPresets.select(r) },
   'agentPreset.read': { schema: agentPresetReadRequestSchema, invoke: (api, r) => api.agentPresets.read(r) },
-  'agentPreset.write': { schema: agentPresetWriteRequestSchema, invoke: (api, r) => api.agentPresets.write(r) },
+  'agentPreset.copy': { schema: agentPresetCopyRequestSchema, invoke: (api, r) => api.agentPresets.copy(r) },
+  'agentPreset.openDocument': { schema: agentPresetOpenDocumentRequestSchema, invoke: (api, r, signal) => api.agentPresets.openDocument(r, signal) },
   'agentPreset.remove': { schema: agentPresetRemoveRequestSchema, invoke: (api, r) => api.agentPresets.remove(r) },
   'goal.create': { schema: goalCreateRequestSchema, invoke: (api, r) => api.goals.create(r) },
   'goal.edit': { schema: goalEditRequestSchema, invoke: (api, r) => api.goals.edit(r) },

packages/host/apiproxy/src/index.ts

@@ -71,6 +71,14 @@ export interface Config {
   model: string
   /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
   workspaceRoot?: string
+  /**
+   * Whether this deployment can hand paths to a native desktop opener —
+   * the `hasDocument` capability the agent-preset roster reports. Absent,
+   * the platform is asked (macOS/Windows/WSL yes; Linux only with a display
+   * server); set it explicitly where detection misleads, e.g. `false` in a
+   * container whose DISPLAY points nowhere a user can see.
+   */
+  nativeOpen?: boolean
 }
 
 /**
@@ -109,6 +117,7 @@ export class ApiProxyService extends Service implements ApiProxy {
     provider: z.string().required(),
     model: z.string().required(),
     workspaceRoot: z.string(),
+    nativeOpen: z.boolean(),
   })
 
   readonly sessions: ApiProxy['sessions']
@@ -154,6 +163,7 @@ export class ApiProxyService extends Service implements ApiProxy {
       },
       cwd,
       workspaceRoot: resolve(config.workspaceRoot ?? cwd),
+      ...config.nativeOpen === undefined ? {} : { canOpenPath: () => config.nativeOpen as boolean },
     })
     this.sessions = api.sessions
     this.subagents = api.subagents

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

@@ -152,6 +152,25 @@ async function openNativePathWithIntent(
   throw new Error(`native path opener is unsupported on ${platform}`)
 }
 
+/**
+ * Whether {@link openNativePath} plausibly reaches a desktop on this host.
+ *
+ * macOS and Windows always carry a desktop opener; Linux does when it is WSL
+ * (the Windows desktop takes the path) or a display server is announced.
+ * A headless or containerised Linux host answers false, which is what lets a
+ * surface show a path as text instead of offering a button that would spawn
+ * `xdg-open` into nothing.
+ * @param internals - platform and environment seam for deterministic tests.
+ * @returns true when handing a path to the native opener can work at all.
+ */
+export function canOpenNativePath(internals: PathOpenerInternals = {}): boolean {
+  const platform = internals.platform ?? process.platform
+  if (platform === 'darwin' || platform === 'win32') return true
+  if (platform !== 'linux') return false
+  const env = internals.env ?? process.env
+  return isWsl(internals) || present(env.DISPLAY) || present(env.WAYLAND_DISPLAY)
+}
+
 /**
  * Open a filesystem path with the operating system's default application, or
  * with the default browser when the path names a document a browser renders.