feat(web): author agent presets from a settings page

A composition is a file, but "edit it on the filesystem" is not a browser
affordance. The roster gains `read`/`write`/`remove` beside `select`, and
the browser gains a settings section over them: the presets as rows, one
composition open in a YAML editor at a time, and per-row default, duplicate,
and delete.

All four authoring methods are 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. `agentPreset.list` deliberately stays ordinary
and now reports `authorable`, so a surface knows whether creating is
possible at all rather than offering a button whose save always fails.

Authoring starts by duplicating: a shipped preset opens read-only because
the deployment's copy is what a broken local one is compared against. Ids
are contained before they become directory names, and the text is parsed
with the loader's own schema, so a save cannot leave a file no session
could load.

Fixes a defect the real-composition test found: a preset written under the
user's home could never mount, because the loader resolves a row against the
composition's own directory and Node's `node_modules` walk from there never
reaches the installed harness. The mount now records the host base and sends
bare specifiers there, leaving relative paths resolving from the preset.

Also closes the coverage the earlier surfaces in this stack shipped without —
the General row, the composer seat, and the plugin halves now have tests.

packages/host/apiproxy/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
-README.md: 963a590f46e3ad41e432ad7ec98666ca180f7426
-README.zh.md: 87f1a702dd754119e34e615f203e1bb073c9f5d4
+README.md: abada8172e0ddc74850e1b3a0ec6b19aee5b8011
+README.zh.md: 833ebf603da94ecd46dec5f8ea8c22b71d164859

packages/host/apiproxy/README.md

@@ -36,6 +36,8 @@ Directory picking delegates to the composed `ctx.directoryPicker` backend ([the
 
 The `agentPreset.list` domain exposes the deployment's preset roster so a browser can offer a choice when starting a session; each row carries its `trust` (a `user` preset is exactly as privileged as the plugins it names) and whether it is the current default. A deployment composing no presets answers with an empty roster rather than an error, because sharing the host composition is a valid deployment. `agentPreset.select` recomposes one session's agent from a different preset, and is allowed only while the session is blank: once a turn has run, that history was produced under the preset's tools and swapping them would strand logged tool calls, so the attempt answers `agent-preset-locked`. The agent and the session survive — only the composition is swapped, and a failed swap restores the previous one.
 
+`agentPreset.read`, `write`, and `remove` author the compositions themselves. `read` reports the text with its `trust` and whether it is `writable`; `write` and `remove` refuse a preset that ships with the deployment, and `write` refuses an id that is not a containable directory name or text that is not a Cordis entry list (`agent-preset-invalid`), a refusal that reaches the caller as `agent-preset-read-only` for the shipped case. Together with `select`, these four are loopback-pinned in [`dsh-client-connection`](../../client/connection/README.md): a composition names the plugins a session runs, so reading one is reconnaissance and writing one is arbitrary capability. `list` stays ordinary — it carries ids and trust, and every preset picker needs it — and reports `authorable`, whether the deployment configures a root a new preset could be written to at all.
+
 The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the browser's user-selected model-reference path, so it returns only skills that are both model-invocable and user-invocable; this domain has no direct skill-loading RPC. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
 
 The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves the namespaces addressed by registered configurable providers (`ctx.llm.listConfigurableProviders()`) plus a small explicit allowlist — the Web preference `permission` and the product-owned `ui-onboarding`; adding a Settings registration alone never makes it remotely readable or writable. Any other namespace answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, the section's `revision`, and the boolean `hasDocument` capability flag. The browser receives no Host path: pathless `settings.openDocument` asks the provider to materialize its document and then hands the Host-resolved result to the native opener, so no browser payload can select an arbitrary filesystem target. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. `llm.discoverModels` interrogates a provider endpoint the page is still drafting: `settingsNs` selects the adapter family that knows how to read the listing, and the endpoint, protocol, and key come from the form rather than from storage. It writes nothing — the reply is candidates, and only a later `settings.mutate` decides what a route serves — so its `apiKey` is the third payload on which a secret may ride, alongside `settings.update`/`mutate` and `credentials.set`. The host never stores or returns it; like the other two it does ride the client's outgoing envelope, which `subscribeEnvelopes()` observers can see, and redacting that tap is a configuration-plane-wide change rather than this method's to make alone. Every refusal (an unserved namespace, a protocol with no readable listing, an unreachable endpoint, a rejected credential) folds into `model-discovery-failed`, whose message is the adapter's own text and whose details name the endpoint asked but never the credential offered. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired by `llm/adapters-updated` and by a change to a configurable-provider namespace, whose settings carry that provider's catalog and endpoint; a `permission` or `ui-onboarding` change emits only its settings invalidation. The browser carrier restricts the whole configuration plane, reads and native actions included (`settings.describe`/`openDocument`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.

packages/host/apiproxy/README.zh.md

@@ -36,6 +36,8 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 `agentPreset.list` 领域向浏览器暴露部署的 preset 名单，使其在开启会话时能够提供选择；每一行携带它的 `trust`（`user` preset 的权限恰好等于它所引用的插件）以及它是否为当前默认值。未组装任何 preset 的部署返回空名单而非错误，因为共用宿主组装本身就是一种有效部署。`agentPreset.select` 用另一个 preset 重组某个会话的 agent，且仅在会话空白时允许：一旦跑过任何轮次，那段历史就是在该 preset 的工具下产生的，替换会留下无法执行的已记录 tool call，此时返回 `agent-preset-locked`。agent 与会话都不销毁——只替换组装，且替换失败会恢复原来的组装。
 
+`agentPreset.read`、`write` 与 `remove` 负责创作组装本身。`read` 返回文本连同它的 `trust` 以及是否 `writable`；`write` 与 `remove` 拒绝随部署提供的 preset，`write` 还拒绝不构成可约束目录名的 id 或不是 Cordis entry 列表的文本（`agent-preset-invalid`），而随部署提供这一情形以 `agent-preset-read-only` 抵达调用方。连同 `select`，这四个方法在 [`dsh-client-connection`](../../client/connection/README.md) 中被固定在环回地址：组装指明了一个会话所运行的插件，因此读取它是侦察，写入它是任意能力。`list` 保持为普通方法——它只携带 id 与信任级别，而每个 preset 选择器都需要它——并报告 `authorable`，即部署是否配置了可供写入新 preset 的根目录。
+
 `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于浏览器中由用户选择的模型引用路径，因此仅返回模型和用户均可调用的 skill；该领域没有直接加载 skill 的 RPC。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
 
 `settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个、也是最后一个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。

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

@@ -25,7 +25,8 @@ import {
 } from '@deepseek-ai/dsh-workspace'
 // Type-only: brings the `ctx.tools` Context merge into this program (viewFor reads presenters).
 import {
-  PresetMountError, resolveSessionPreset, UnknownPresetError,
+  InvalidCompositionError, InvalidPresetIdError, PresetMountError,
+  PresetNotWritableError, resolveSessionPreset, UnknownPresetError,
 } from '@deepseek-ai/dsh-agent-presets'
 import type {} from '@deepseek-ai/dsh-tools'
 import type {
@@ -658,6 +659,33 @@ class SubagentSessionOwnership extends Error {
  * replay tool calls the rebuilt agent cannot make. Naming a different preset
  * is therefore a caller error rather than a switch.
  */
+/** The roster is absent: this deployment composes no agent presets at all. */
+function noRoster(agentPreset: string): RpcError {
+  return {
+    code: 'agent-preset-not-found',
+    message: 'this deployment composes no agent presets',
+    details: { agentPreset, available: [] },
+  }
+}
+
+/** Map one authoring/roster failure onto its wire code. */
+function presetError(agentPreset: string, error: unknown): RpcError {
+  if (error instanceof UnknownPresetError) {
+    return {
+      code: 'agent-preset-not-found',
+      message: error.message,
+      details: { agentPreset: error.presetId, available: [...error.available] },
+    }
+  }
+  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) {
+    return { code: 'agent-preset-invalid', message: error.message, details: { agentPreset, reason: error.message } }
+  }
+  return { code: 'internal', message: `agent preset "${agentPreset}": ${String(error)}`, details: {} }
+}
+
 class AgentPresetConflict extends Error {
   constructor(
     readonly sessionId: SessionId,
@@ -2501,7 +2529,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: [] })
+        if (presets === undefined) return ok(request, { presets: [], authorable: false })
         const defaultId = presets.defaultId
         return ok(request, {
           presets: (await presets.list()).map(preset => ({
@@ -2509,6 +2537,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             trust: preset.trust,
             isDefault: preset.id === defaultId,
           })),
+          authorable: presets.authorable,
         })
       },
 
@@ -2563,6 +2592,50 @@ 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.
+      async read(request) {
+        const { agentPreset } = request.payload
+        const presets = ctx.get('agentPresets')
+        if (presets === undefined) return err(request, noRoster(agentPreset))
+        try {
+          const preset = await presets.resolve(agentPreset)
+          return ok(request, {
+            agentPreset: preset.id,
+            trust: preset.trust,
+            content: await presets.read(preset.id),
+            writable: preset.trust === 'user' && presets.authorable,
+          })
+        } catch (error: unknown) {
+          return err(request, presetError(agentPreset, error))
+        }
+      },
+
+      async write(request) {
+        const { agentPreset, content } = request.payload
+        const presets = ctx.get('agentPresets')
+        if (presets === undefined) return err(request, noRoster(agentPreset))
+        try {
+          await presets.write(agentPreset, content)
+          return ok(request, { agentPreset })
+        } catch (error: unknown) {
+          return err(request, presetError(agentPreset, error))
+        }
+      },
+
+      async remove(request) {
+        const { agentPreset } = request.payload
+        const presets = ctx.get('agentPresets')
+        if (presets === undefined) return err(request, noRoster(agentPreset))
+        try {
+          await presets.remove(agentPreset)
+          return ok(request, {})
+        } catch (error: unknown) {
+          return err(request, presetError(agentPreset, error))
+        }
+      },
     },
 
     skills: {

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

@@ -23,6 +23,7 @@ export const agentPresetListRequestSchema = z.object({
 /** agentPreset.list response value. */
 export const agentPresetListValueSchema = z.object({
   presets: z.array(agentPresetEntrySchema),
+  authorable: z.boolean(),
 }) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.list'>>>
 
 /** agentPreset.select request payload. */
@@ -35,3 +36,36 @@ export const agentPresetSelectRequestSchema = z.object({
 export const agentPresetSelectValueSchema = z.object({
   agentPreset: z.string(),
 }) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.select'>>>
+
+/** agentPreset.read request payload. */
+export const agentPresetReadRequestSchema = z.object({
+  agentPreset: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.read'>>>
+
+/** agentPreset.read response value. */
+export const agentPresetReadValueSchema = z.object({
+  agentPreset: z.string(),
+  trust: z.union([z.literal('system'), z.literal('user')]),
+  content: z.string(),
+  writable: z.boolean(),
+}) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.read'>>>
+
+/** agentPreset.write request payload. */
+export const agentPresetWriteRequestSchema = z.object({
+  agentPreset: z.string().min(1),
+  content: z.string(),
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.write'>>>
+
+/** agentPreset.write response value. */
+export const agentPresetWriteValueSchema = z.object({
+  agentPreset: z.string(),
+}) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.write'>>>
+
+/** agentPreset.remove request payload. */
+export const agentPresetRemoveRequestSchema = z.object({
+  agentPreset: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'agentPreset.remove'>>>
+
+/** agentPreset.remove response value. */
+export const agentPresetRemoveValueSchema = z.object({
+}) satisfies z.ZodType<Wire<ResponseValue<'agentPreset.remove'>>>

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

@@ -1,7 +1,12 @@
 /**
  * agent-presets domain contract: the roster a browser offers when starting a
- * session. Read-only — a preset is a composition on disk, and authoring one is
- * a filesystem act rather than an RPC.
+ * 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.
  */
 
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -26,9 +31,12 @@ export interface AgentPresetsApi {
   /**
    * Lists every preset the deployment currently supplies, ordered by id.
    * An empty roster means the deployment composes no presets at all, and
-   * every session shares the host composition.
+   * 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.
    */
-  list(request: RpcRequest<{}>): Promise<RpcResponse<{ presets: readonly AgentPresetEntry[] }>>
+  list(request: RpcRequest<{}>):
+  Promise<RpcResponse<{ presets: readonly AgentPresetEntry[]; authorable: boolean }>>
 
   /**
    * Recompose one session's agent from a different preset.
@@ -40,4 +48,24 @@ export interface AgentPresetsApi {
    */
   select(request: RpcRequest<{ sessionId: SessionId; agentPreset: string }>):
   Promise<RpcResponse<{ agentPreset: string }>>
+
+  /**
+   * Read one preset's composition text, for an editor.
+   *
+   * Privileged: a composition names the plugins a session runs, so reading one
+   * is reconnaissance and writing one is arbitrary capability.
+   */
+  read(request: RpcRequest<{ agentPreset: string }>):
+  Promise<RpcResponse<{ agentPreset: string; trust: 'system' | 'user'; content: string; writable: boolean }>>
+
+  /**
+   * 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.
+   */
+  write(request: RpcRequest<{ agentPreset: string; content: string }>):
+  Promise<RpcResponse<{ agentPreset: 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

@@ -53,6 +53,9 @@ export interface RpcMethodMap {
   'skill.list': SkillsApi['list']
   'agentPreset.list': AgentPresetsApi['list']
   'agentPreset.select': AgentPresetsApi['select']
+  'agentPreset.read': AgentPresetsApi['read']
+  'agentPreset.write': AgentPresetsApi['write']
+  'agentPreset.remove': AgentPresetsApi['remove']
   'goal.create': GoalsApi['create']
   'goal.edit': GoalsApi['edit']
   'goal.pause': GoalsApi['pause']

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

@@ -46,6 +46,7 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('directory-exists'), message: z.string(), details: z.object({ path: z.string() }) }),
   z.object({ code: z.literal('directory-create-failed'), message: z.string(), details: z.object({ path: z.string() }) }),
   z.object({ code: z.literal('directory-picker-unavailable'), message: z.string(), details: z.object({ capability: z.string() }) }),
+  z.object({ code: z.literal('agent-preset-read-only'), message: z.string(), details: z.object({ agentPreset: z.string(), reason: z.string() }) }),
   z.object({ code: z.literal('agent-preset-locked'), message: z.string(), details: z.object({ sessionId: z.string(), agentPreset: z.string() }) }),
   z.object({ code: z.literal('agent-preset-conflict'), message: z.string(), details: z.object({ sessionId: z.string(), requestedPreset: z.string(), existingPreset: z.string().optional() }) }),
   z.object({ code: z.literal('agent-preset-not-found'), message: z.string(), details: z.object({ agentPreset: z.string(), available: z.array(z.string()) }) }),

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

@@ -44,6 +44,7 @@ export interface RpcErrorDetailsMap {
   'directory-exists': { path: string }
   'directory-create-failed': { path: string }
   'directory-picker-unavailable': { capability: string }
+  'agent-preset-read-only': { agentPreset: string; reason: string }
   'agent-preset-locked': { sessionId: SessionId; agentPreset: string }
   'agent-preset-conflict': { sessionId: SessionId; requestedPreset: string; existingPreset?: string }
   'agent-preset-not-found': { agentPreset: string; available: string[] }

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

@@ -40,7 +40,10 @@ import {
 } from '../api/workspace.schema.ts'
 import { commandExecuteValueSchema, commandListValueSchema } from '../api/commands.schema.ts'
 import { skillListValueSchema } from '../api/skills.schema.ts'
-import { agentPresetListValueSchema, agentPresetSelectValueSchema } from '../api/agent-presets.schema.ts'
+import {
+  agentPresetListValueSchema, agentPresetReadValueSchema, agentPresetRemoveValueSchema,
+  agentPresetSelectValueSchema, agentPresetWriteValueSchema,
+} from '../api/agent-presets.schema.ts'
 import {
   goalCreateValueSchema,
   goalEditValueSchema,
@@ -123,6 +126,9 @@ export interface IApiClient {
   readonly agentPresets: {
     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'>>>
+    remove(payload: RequestPayload<'agentPreset.remove'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'agentPreset.remove'>>>
   }
   events: {
     mux(payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>
@@ -192,6 +198,9 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'skill.list': skillListValueSchema,
   'agentPreset.list': agentPresetListValueSchema,
   'agentPreset.select': agentPresetSelectValueSchema,
+  'agentPreset.read': agentPresetReadValueSchema,
+  'agentPreset.write': agentPresetWriteValueSchema,
+  'agentPreset.remove': agentPresetRemoveValueSchema,
   'goal.create': goalCreateValueSchema,
   'goal.edit': goalEditValueSchema,
   'goal.pause': goalPauseValueSchema,
@@ -455,6 +464,12 @@ export abstract class AbstractApiClient implements IApiClient {
       this.callUnary('agentPreset.list', payload, signal),
     select: (payload: RequestPayload<'agentPreset.select'>, signal?: AbortSignal) =>
       this.callUnary('agentPreset.select', payload, signal),
+    read: (payload: RequestPayload<'agentPreset.read'>, signal?: AbortSignal) =>
+      this.callUnary('agentPreset.read', payload, signal),
+    write: (payload: RequestPayload<'agentPreset.write'>, signal?: AbortSignal) =>
+      this.callUnary('agentPreset.write', payload, signal),
+    remove: (payload: RequestPayload<'agentPreset.remove'>, signal?: AbortSignal) =>
+      this.callUnary('agentPreset.remove', payload, signal),
   }
 
   readonly goals: IApiClient['goals'] = {

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

@@ -42,7 +42,10 @@ import {
 } from '../api/workspace.schema.ts'
 import { commandExecuteRequestSchema, commandListRequestSchema } from '../api/commands.schema.ts'
 import { skillListRequestSchema } from '../api/skills.schema.ts'
-import { agentPresetListRequestSchema, agentPresetSelectRequestSchema } from '../api/agent-presets.schema.ts'
+import {
+  agentPresetListRequestSchema, agentPresetReadRequestSchema, agentPresetRemoveRequestSchema,
+  agentPresetSelectRequestSchema, agentPresetWriteRequestSchema,
+} from '../api/agent-presets.schema.ts'
 import {
   goalCreateRequestSchema,
   goalEditRequestSchema,
@@ -112,6 +115,9 @@ const UNARY_ROUTES: UnaryRoutes = {
   'skill.list': { schema: skillListRequestSchema, invoke: (api, r) => api.skills.list(r) },
   '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.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) },
   'goal.pause': { schema: goalPauseRequestSchema, invoke: (api, r) => api.goals.pause(r) },

packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts

@@ -14,7 +14,9 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 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 { UnknownPresetError } from '@deepseek-ai/dsh-agent-presets'
+import {
+  InvalidCompositionError, InvalidPresetIdError, UnknownPresetError,
+} from '@deepseek-ai/dsh-agent-presets'
 import { GoalId } from '@deepseek-ai/dsh-goal'
 import { createApiProxy } from '../src/api-proxy.ts'
 import { describe, expect, it } from 'vitest'
@@ -52,6 +54,19 @@ function roster(ids: readonly string[]): unknown {
       const perAgent = services.get(String(agent.id))
       return perAgent?.[name]
     },
+    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'))
+      return Promise.resolve()
+    },
+    remove: (id: string) => {
+      if (!ids.includes(id)) return Promise.reject(new UnknownPresetError(id, ids))
+      return Promise.resolve()
+    },
     recompose: (_ctx: Context, id: string) => {
       if (!ids.includes(id)) return Promise.reject(new UnknownPresetError(id, ids))
       return Promise.resolve({ id, trust: 'system', path: `/presets/${id}.yml` })
@@ -252,6 +267,7 @@ describe('agentPreset.list', () => {
       { id: 'standard', trust: 'system', isDefault: true },
       { id: 'core-web', trust: 'system', isDefault: false },
     ])
+    expect(response.result.value.authorable).toBe(true)
   })
 
   it('answers with an empty roster when the deployment composes no presets', async () => {
@@ -264,6 +280,9 @@ describe('agentPreset.list', () => {
     expect(response.result.ok).toBe(true)
     if (!response.result.ok) throw new Error('unreachable')
     expect(response.result.value.presets).toEqual([])
+    // Nothing to write to either, so a surface offering "new preset" knows to
+    // stay hidden rather than offering a button whose save always fails.
+    expect(response.result.value.authorable).toBe(false)
   })
 })
 
@@ -319,3 +338,59 @@ describe('agentPreset.select', () => {
     expect(response.result.error.code).toBe('agent-preset-not-found')
   })
 })
+
+describe('authoring over the wire', () => {
+  it('reads a composition and reports whether it may be edited', 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.
+    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 () => {
+    const { api } = await harness(['standard'])
+
+    const response = await api.agentPresets.write(request({ agentPreset: '../escape', content: '- id: x\n' }))
+
+    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'])
+
+    const response = await api.agentPresets.write(request({ agentPreset: 'mine', content: 'tools: []\n' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-invalid')
+  })
+
+  it('reports a deployment that composes no presets', async () => {
+    const { api } = await harness()
+
+    const response = await api.agentPresets.read(request({ agentPreset: 'anything' }))
+
+    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 an unknown id on delete rather than succeeding silently', async () => {
+    const { api } = await harness(['standard'])
+
+    const response = await api.agentPresets.remove(request({ agentPreset: 'never-existed' }))
+
+    expect(response.result.ok).toBe(false)
+    if (response.result.ok) throw new Error('unreachable')
+    expect(response.result.error.code).toBe('agent-preset-not-found')
+  })
+})

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

@@ -88,8 +88,11 @@ function scriptedApi(overrides: {
     },
     skills: { list: r => ok(r, { skills: [] }), ...overrides.skills },
     agentPresets: {
-      list: r => ok(r, { presets: [] }),
+      list: r => ok(r, { presets: [], authorable: 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 }),
+      remove: r => ok(r, {}),
       ...overrides.agentPresets,
     },
     goals: {

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

@@ -195,12 +195,26 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
     },
     agentPresets: {
       list(request: RpcRequest<{}>) {
-        return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value: { presets: [] } } })
+        return Promise.resolve({
+          rpcId: request.rpcId,
+          result: { ok: true as const, value: { presets: [], authorable: false } },
+        })
       },
       select(request: RpcRequest<{ agentPreset: string }>) {
         const value = { agentPreset: request.payload.agentPreset }
         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 }
+        return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value } })
+      },
+      write(request: RpcRequest<{ agentPreset: string }>) {
+        const value = { agentPreset: request.payload.agentPreset }
+        return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value } })
+      },
+      remove(request: RpcRequest<{ agentPreset: string }>) {
+        return Promise.resolve({ rpcId: request.rpcId, result: { ok: true as const, value: {} } })
+      },
     },
     skills: {
       async list(request) {

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

@@ -513,6 +513,9 @@ describe('agent-preset schemas', () => {
   })
 
   it('accepts an empty roster', () => {
-    expect(agentPresetListValueSchema.parse({ presets: [] })).toEqual({ presets: [] })
+    // 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 })
   })
 })