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/tests/api-proxy-agent-preset.spec.ts

@@ -15,7 +15,7 @@ import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import { RpcId, type RpcRequest } from '../src/api/rpc.ts'
 import {
-  InvalidCompositionError, InvalidPresetIdError, resolveSessionPreset, UnknownPresetError,
+  InvalidPresetIdError, PresetExistsError, resolveSessionPreset, UnknownPresetError,
 } from '@deepseek-ai/dsh-agent-presets'
 import { GoalId } from '@deepseek-ai/dsh-goal'
 import { createApiProxy } from '../src/api-proxy.ts'
@@ -34,19 +34,22 @@ function stubAgent(session: Session): Agent {
 /**
  * A roster whose `mount` is a no-op: this spec is about the gateway's identity
  * rules, and the composition itself is covered by the real-composition test in
- * `apps/cli`.
+ * `apps/cli`. Ids listed in `userIds` present as locally authored; the rest
+ * ship with the deployment.
  */
-function roster(ids: readonly string[]): unknown {
+function roster(ids: readonly string[], userIds: readonly string[] = []): unknown {
+  const trustOf = (id: string): 'system' | 'user' => (userIds.includes(id) ? 'user' : 'system')
+  const presetOf = (id: string): object =>
+    ({ id, trust: trustOf(id), path: `/presets/${id}/agent.cordis.yml` })
   return {
     defaultId: ids[0],
-    list: () => Promise.resolve(ids.map(id => ({ id, trust: 'system', path: `/presets/${id}.yml` }))),
+    list: () => Promise.resolve(ids.map(presetOf)),
     resolve: (id?: string) => {
       const wanted = id ?? ids[0] ?? ''
       if (!ids.includes(wanted)) return Promise.reject(new UnknownPresetError(wanted, ids))
-      return Promise.resolve({ id: wanted, trust: 'system', path: `/presets/${wanted}.yml` })
+      return Promise.resolve(presetOf(wanted))
     },
-    mount: (_ctx: Context, id?: string) =>
-      Promise.resolve({ id: id ?? ids[0], trust: 'system', path: '/presets/x.yml' }),
+    mount: (_ctx: Context, id?: string) => Promise.resolve(presetOf(id ?? ids[0] ?? '')),
     // What a real mount leaves behind: a service instance only the agent that
     // mounted it can be used to address. The doubles are per agent so a test
     // can tell "this session's" from "some session's".
@@ -56,11 +59,10 @@ function roster(ids: readonly string[]): unknown {
     },
     authorable: true,
     read: (id: string) => Promise.resolve(`# ${id}\n- id: x\n  name: y\n`),
-    write: (id: string, content: string) => {
-      if (!ids.includes(id) && !/^[a-z0-9][a-z0-9-]*$/.test(id)) {
-        return Promise.reject(new InvalidPresetIdError(id))
-      }
-      if (!content.trimStart().startsWith('-')) return Promise.reject(new InvalidCompositionError('not a list'))
+    copy: (from: string, id: string) => {
+      if (!ids.includes(from)) return Promise.reject(new UnknownPresetError(from, ids))
+      if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) return Promise.reject(new InvalidPresetIdError(id))
+      if (ids.includes(id)) return Promise.reject(new PresetExistsError(id))
       return Promise.resolve()
     },
     remove: (id: string) => {
@@ -97,14 +99,18 @@ const failingStandingKeys = new Set<string>()
 /** Per-agent service instances a mounted preset would own, keyed by session id. */
 const services = new Map<string, Record<string, unknown>>()
 
-async function harness(presets?: readonly string[], persistence?: unknown) {
+async function harness(
+  presets?: readonly string[],
+  persistence?: unknown,
+  options: { userIds?: readonly string[]; defaults?: Record<string, unknown> } = {},
+) {
   const cwd = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-apiproxy-preset-')))
   const ctx = new Context()
   await ctx.plugin(SessionStore)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(UserInteractionService)
   ctx.provide('sessionPersistence', (persistence ?? { list: () => Promise.resolve([]) }) as never)
-  if (presets !== undefined) ctx.provide('agentPresets', roster(presets) as never)
+  if (presets !== undefined) ctx.provide('agentPresets', roster(presets, options.userIds) as never)
 
   const factory: AgentFactory = {
     async createAgent(_ownerCtx, options) {
@@ -131,6 +137,7 @@ async function harness(presets?: readonly string[], persistence?: unknown) {
     defaultTarget: () => ({ provider: 'test', model: 'test-model' }),
     cwd,
     workspaceRoot: cwd,
+    ...options.defaults,
   })
   return { api, ctx, cwd }
 }
@@ -404,38 +411,59 @@ describe('agentPreset.select', () => {
 })
 
 describe('authoring over the wire', () => {
-  it('reads a composition and reports whether it may be edited', async () => {
+  it('reads a composition with its trust', async () => {
     const { api } = await harness(['standard'])
 
     const response = await api.agentPresets.read(request({ agentPreset: 'standard' }))
 
     expect(response.result.ok).toBe(true)
     if (!response.result.ok) throw new Error('unreachable')
-    // The shipped set is readable but not writable: it belongs to the
-    // deployment, and it is what a broken local preset is compared against.
+    // The shipped set is readable: it is the known-good composition a copy
+    // starts from, and trust is what tells a surface to say so.
     expect(response.result.value.trust).toBe('system')
-    expect(response.result.value.writable).toBe(false)
     expect(response.result.value.content).toContain('- id: x')
   })
 
-  it('rejects an id that could escape the preset root', async () => {
+  it('copies a preset under a new id', async () => {
     const { api } = await harness(['standard'])
 
-    const response = await api.agentPresets.write(request({ agentPreset: '../escape', content: '- id: x\n' }))
+    const response = await api.agentPresets.copy(
+      request({ from: 'standard', agentPreset: 'mine', name: '我的模式' }))
+
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value.agentPreset).toBe('mine')
+  })
+
+  it('rejects a copy target that could escape the preset root', async () => {
+    const { api } = await harness(['standard'])
+
+    const response = await api.agentPresets.copy(request({ from: 'standard', agentPreset: '../escape' }))
 
     expect(response.result.ok).toBe(false)
     if (response.result.ok) throw new Error('unreachable')
     expect(response.result.error.code).toBe('agent-preset-invalid')
   })
 
-  it('rejects content that is not an entry list', async () => {
-    const { api } = await harness(['standard'])
+  it('rejects a copy target the roster already supplies', async () => {
+    const { api } = await harness(['standard', 'minimal'])
 
-    const response = await api.agentPresets.write(request({ agentPreset: 'mine', content: 'tools: []\n' }))
+    const response = await api.agentPresets.copy(request({ from: 'standard', agentPreset: 'minimal' }))
 
     expect(response.result.ok).toBe(false)
     if (response.result.ok) throw new Error('unreachable')
     expect(response.result.error.code).toBe('agent-preset-invalid')
+    expect(response.result.error.message).toMatch(/already exists/)
+  })
+
+  it('rejects a copy whose source is unknown', async () => {
+    const { api } = await harness(['standard'])
+
+    const response = await api.agentPresets.copy(request({ from: 'never-existed', agentPreset: 'mine' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-not-found')
   })
 
   it('reports a deployment that composes no presets', async () => {
@@ -459,6 +487,81 @@ describe('authoring over the wire', () => {
   })
 })
 
+describe('opening a preset directory', () => {
+  it('hands the resolved directory to the native opener', async () => {
+    const opened: string[] = []
+    const { api } = await harness(['standard', 'my-preset'], undefined, {
+      userIds: ['my-preset'],
+      defaults: { openPath: (path: string) => { opened.push(path); return Promise.resolve() } },
+    })
+
+    const response = await api.agentPresets.openDocument(
+      request({ agentPreset: 'my-preset' }), new AbortController().signal)
+
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value).toEqual({ opened: true })
+    // The id selected the directory; the browser supplied no path.
+    expect(opened).toEqual(['/presets/my-preset'])
+  })
+
+  it('answers the path as text where the deployment has no opener', async () => {
+    const { api } = await harness(['standard', 'my-preset'], undefined, {
+      userIds: ['my-preset'],
+      defaults: { canOpenPath: () => false },
+    })
+
+    const response = await api.agentPresets.openDocument(
+      request({ agentPreset: 'my-preset' }), new AbortController().signal)
+
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect(response.result.value).toEqual({ opened: false, path: '/presets/my-preset' })
+  })
+
+  it('refuses a preset that ships with the deployment', async () => {
+    const opened: string[] = []
+    const { api } = await harness(['standard'], undefined, {
+      defaults: { openPath: (path: string) => { opened.push(path); return Promise.resolve() } },
+    })
+
+    const response = await api.agentPresets.openDocument(
+      request({ agentPreset: 'standard' }), new AbortController().signal)
+
+    // Pointing an editor into the install invites edits an upgrade will
+    // silently overwrite; the refusal mirrors copy/remove.
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-read-only')
+    expect(opened).toEqual([])
+  })
+
+  it('reports the roster capability on list', async () => {
+    const openable = await harness(['standard'], undefined, {
+      defaults: { canOpenPath: () => true },
+    })
+    const headless = await harness(['standard'], undefined, {
+      defaults: { canOpenPath: () => false },
+    })
+
+    const yes = await openable.api.agentPresets.list(request({}))
+    const no = await headless.api.agentPresets.list(request({}))
+
+    expect(yes.result.ok && yes.result.value.hasDocument).toBe(true)
+    expect(no.result.ok && no.result.value.hasDocument).toBe(false)
+  })
+
+  it('counts an injected opener as openable', async () => {
+    const { api } = await harness(['standard'], undefined, {
+      defaults: { openPath: () => Promise.resolve() },
+    })
+
+    const response = await api.agentPresets.list(request({}))
+
+    expect(response.result.ok && response.result.value.hasDocument).toBe(true)
+  })
+})
+
 describe('session.history presenter scope', () => {
   it('asks the roster for the RECORDED preset\'s standing key on a cold read', async () => {
     const { api } = await harness(['standard', 'core-web'])

packages/host/apiproxy/tests/client-handler.spec.ts

@@ -89,10 +89,11 @@ function scriptedApi(overrides: {
     },
     skills: { list: r => ok(r, { skills: [] }), ...overrides.skills },
     agentPresets: {
-      list: r => ok(r, { presets: [], authorable: false }),
+      list: r => ok(r, { presets: [], authorable: false, hasDocument: false }),
       select: r => ok(r, { agentPreset: r.payload.agentPreset }),
-      read: r => ok(r, { agentPreset: r.payload.agentPreset, trust: 'user' as const, content: '', writable: true }),
-      write: r => ok(r, { agentPreset: r.payload.agentPreset }),
+      read: r => ok(r, { agentPreset: r.payload.agentPreset, trust: 'user' as const, content: '' }),
+      copy: r => ok(r, { agentPreset: r.payload.agentPreset }),
+      openDocument: r => ok(r, { opened: true as const }),
       remove: r => ok(r, {}),
       ...overrides.agentPresets,
     },
@@ -234,7 +235,7 @@ describe('unary round trip', () => {
     const c = client(scriptedApi())
 
     const listed = await c.agentPresets.list({})
-    expect(listed.result).toEqual({ ok: true, value: { presets: [], authorable: false } })
+    expect(listed.result).toEqual({ ok: true, value: { presets: [], authorable: false, hasDocument: false } })
 
     // The switch carries the session it is about: the host refuses one whose
     // conversation has started, and it can only know which by id.

packages/host/apiproxy/tests/fetch-carrier.spec.ts

@@ -198,7 +198,7 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
       list(request: RpcRequest<{}>) {
         return Promise.resolve({
           rpcId: request.rpcId,
-          result: { ok: true as const, value: { presets: [], authorable: false } },
+          result: { ok: true as const, value: { presets: [], authorable: false, hasDocument: false } },
         })
       },
       select(request: RpcRequest<{ agentPreset: string }>) {
@@ -206,13 +206,16 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
         return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value } })
       },
       read(request: RpcRequest<{ agentPreset: string }>) {
-        const value = { agentPreset: request.payload.agentPreset, trust: 'user' as const, content: '', writable: true }
+        const value = { agentPreset: request.payload.agentPreset, trust: 'user' as const, content: '' }
         return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value } })
       },
-      write(request: RpcRequest<{ agentPreset: string }>) {
+      copy(request: RpcRequest<{ from: string; agentPreset: string }>) {
         const value = { agentPreset: request.payload.agentPreset }
         return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value } })
       },
+      openDocument(request: RpcRequest<{ agentPreset: string }>) {
+        return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value: { opened: true as const } } })
+      },
       remove(request: RpcRequest<{ agentPreset: string }>) {
         return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value: {} } })
       },
@@ -364,19 +367,21 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     const c = client()
 
     // The whole domain crosses the carrier: the roster a picker reads, the
-    // per-session switch, and the three authoring calls the settings editor
-    // makes. Each has its own request schema, so a registration missing from
-    // either half fails here rather than in the browser.
+    // per-session switch, and the authoring calls the settings page makes.
+    // Each has its own request schema, so a registration missing from either
+    // half fails here rather than in the browser.
     expect((await c.agentPresets.list({})).result).toEqual({
-      ok: true, value: { presets: [], authorable: false },
+      ok: true, value: { presets: [], authorable: false, hasDocument: false },
     })
     expect((await c.agentPresets.select({ sessionId: 's' as never, agentPreset: 'minimal' })).result)
       .toEqual({ ok: true, value: { agentPreset: 'minimal' } })
     expect((await c.agentPresets.read({ agentPreset: 'mine' })).result).toEqual({
-      ok: true, value: { agentPreset: 'mine', trust: 'user', content: '', writable: true },
+      ok: true, value: { agentPreset: 'mine', trust: 'user', content: '' },
     })
-    expect((await c.agentPresets.write({ agentPreset: 'mine', content: '- id: x\n' })).result)
+    expect((await c.agentPresets.copy({ from: 'standard', agentPreset: 'mine' })).result)
       .toEqual({ ok: true, value: { agentPreset: 'mine' } })
+    expect((await c.agentPresets.openDocument({ agentPreset: 'mine' })).result)
+      .toEqual({ ok: true, value: { opened: true } })
     expect((await c.agentPresets.remove({ agentPreset: 'mine' })).result).toEqual({ ok: true, value: {} })
   })
 

packages/host/apiproxy/tests/native-path-opener.spec.ts

@@ -16,7 +16,7 @@ vi.mock('node:child_process', () => ({ execFile: execFileMock }))
 
 import { release as osRelease } from 'node:os'
 import { describe, expect, it, vi } from 'vitest'
-import { openNativePath, openNativeTextFile, type PathOpenerRunner } from '../src/native-path-opener.ts'
+import { canOpenNativePath, openNativePath, openNativeTextFile, type PathOpenerRunner } from '../src/native-path-opener.ts'
 
 const signal = () => new AbortController().signal
 
@@ -287,3 +287,35 @@ describe('browser-renderable documents', () => {
     ])
   })
 })
+
+describe('canOpenNativePath', () => {
+  it('always answers yes where the desktop is part of the platform', () => {
+    expect(canOpenNativePath({ platform: 'darwin', env: {} })).toBe(true)
+    expect(canOpenNativePath({ platform: 'win32', env: {} })).toBe(true)
+  })
+
+  it('requires a display server or WSL interop on linux', () => {
+    const linux = { platform: 'linux' as const, osRelease: '6.8.0-generic' }
+    // Headless is the case the capability exists for: `xdg-open` would spawn
+    // into nothing, so a surface should show the path as text instead.
+    expect(canOpenNativePath({ ...linux, env: {} })).toBe(false)
+    expect(canOpenNativePath({ ...linux, env: { DISPLAY: ':0' } })).toBe(true)
+    expect(canOpenNativePath({ ...linux, env: { WAYLAND_DISPLAY: 'wayland-0' } })).toBe(true)
+    expect(canOpenNativePath({
+      platform: 'linux', osRelease: '5.15.153.1-microsoft-standard-WSL2', env: {},
+    })).toBe(true)
+  })
+
+  it('answers no on a platform the opener does not support', () => {
+    expect(canOpenNativePath({ platform: 'freebsd', env: {} })).toBe(false)
+  })
+
+  it('samples the ambient environment when no override is supplied', () => {
+    const env = process.env
+    const marked = (value: string | undefined): boolean => value !== undefined && value !== ''
+    const expected = marked(env.WSL_DISTRO_NAME) || marked(env.WSL_INTEROP)
+      || marked(env.DISPLAY) || marked(env.WAYLAND_DISPLAY)
+
+    expect(canOpenNativePath({ platform: 'linux', osRelease: '6.8.0-generic' })).toBe(expected)
+  })
+})

packages/host/apiproxy/tests/rpc-schemas.spec.ts

@@ -32,7 +32,9 @@ import {
   commandListRequestSchema, commandListValueSchema,
 } from '../src/api/commands.schema.ts'
 import { skillEntrySchema, skillListRequestSchema, skillListValueSchema } from '../src/api/skills.schema.ts'
-import { agentPresetEntrySchema, agentPresetListValueSchema } from '../src/api/agent-presets.schema.ts'
+import {
+  agentPresetEntrySchema, agentPresetListValueSchema, agentPresetOpenDocumentValueSchema,
+} from '../src/api/agent-presets.schema.ts'
 import { hostFrameSchema, muxFrameSchema, askUserQuestionItemSchema } from '../src/api/events.schema.ts'
 import { approvalRequestIdSchema, approvalResponsePayloadSchema } from '../src/api/approvals.schema.ts'
 import { askUserQuestionAnswerSchema, questionResponsePayloadSchema } from '../src/api/questions.schema.ts'
@@ -516,9 +518,17 @@ describe('agent-preset schemas', () => {
   })
 
   it('accepts an empty roster', () => {
-    // A deployment composing no presets still reports whether one could be
-    // written, so a surface knows to offer creation rather than nothing at all.
-    expect(agentPresetListValueSchema.parse({ presets: [], authorable: false }))
-      .toEqual({ presets: [], authorable: false })
+    // A deployment composing no presets still reports its authoring and
+    // native-open capabilities, so a surface knows what to offer.
+    expect(agentPresetListValueSchema.parse({ presets: [], authorable: false, hasDocument: false }))
+      .toEqual({ presets: [], authorable: false, hasDocument: false })
+  })
+
+  it('answers the open-document union by its discriminant', () => {
+    expect(agentPresetOpenDocumentValueSchema.parse({ opened: true })).toEqual({ opened: true })
+    expect(agentPresetOpenDocumentValueSchema.parse({ opened: false, path: '/presets/mine' }))
+      .toEqual({ opened: false, path: '/presets/mine' })
+    // A closed reply must carry the path the surface shows instead.
+    expect(() => agentPresetOpenDocumentValueSchema.parse({ opened: false })).toThrow()
   })
 })