feat(permission): user-facing permission presets — one Permissions select over the two knobs

A preset names a bundle of the two mechanism knobs — request = workspace-write + ask, yolo = danger-full-access + never — so the editor shows ONE 'Permissions' select where the sandbox-mode and approval-policy tiers stay orthogonal capabilities (the Codex /approvals shape: presets over two dials). ctx.permission (dsh-permission) owns the config-defined table, validates the default preset's bundle against the composed knob defaults at load (fails loud), and writes a switch THROUGH: one log-only permission/preset event (the audit fact reverse-mapping cannot recover — the planned 'agent' preset shares request's knob values and differs only in composed policy) plus each knob event via its own setter, deduped — a net-zero switch appends nothing. Every knob consumer keeps reading its own fold, untouched. The current preset DERIVES from the effective knob values — the fold breaks bundle ties, a knob state outside the table is the reserved 'custom' value (a state, not an error: shown while it holds, switchable FROM, never a target), and defaultPreset disappears (zero-event state reverse-maps from the composition defaults). The ACP bridge drops the two per-knob selects for the one preset select (advertised only when ctx.permission is composed); pending/anchor/no-op semantics carry over unchanged, with the no-op echo acknowledged before vocabulary validation so a client re-pushing a derived 'custom' current never errors. The sandbox variant example composes the service with a workspace-write default; the permission-switching, escalation-approved and escalation-rejected scenarios are re-recorded under it (escalations now target an outside-workspace /tmp path under danger-full-access, self-cleaning) and config-options is re-authored on the single-select wire.
2026-07-12 21:03:41 +08:00
parent 624d8d5df4
commit 95635dfa66
40 changed files with 1724 additions and 1062 deletions
--- a/packages/ui/permission/README.md
+++ b/packages/ui/permission/README.md
@@ -0,0 +1,7 @@
+# @deepseek-ai/dsh-permission
+
+User-facing permission presets. Owns the `ctx.permission` service ([`PermissionService`](src/index.ts)): a config-defined preset table — by default `request` (`workspace-write` + `ask`) and `yolo` (`danger-full-access` + `never`) — where each name bundles the two mechanism knobs, `bash/sandbox-mode` and `approval/policy`. The product surface (the ACP bridge's single `Permissions` select) advertises `names` and calls `set()`; the mechanism tiers stay orthogonal capabilities that never learn the product vocabulary.
+
+A switch WRITES THROUGH: `set(session, name)` appends one log-only `permission/preset` event when the name differs from the session's current preset (the audit fact reverse-mapping cannot recover — two presets may share knob values and differ only in composed policy, the planned `agent` preset being the standing example), then each knob event through its own THE-write-path setter, skipping values the session already effectively has — a net-zero switch appends nothing. The current preset DERIVES from the effective knob values (fold ?? composition default per knob): the last-chosen preset when its bundle still matches (presets may share bundles — the fold breaks the tie), else the first matching table entry, else the reserved `custom` — the honest not-a-preset state, shown as the current value only while it holds, switchable FROM and never a target. Every existing knob consumer (executor stamping, the approval gate, narrators, resume) keeps reading its own fold, untouched.
+
+Composing it requires a confining `ctx.bash` executor and the `ctx.approval` seam; a table entry named `custom` throws at load (the name is reserved), while composition defaults outside the table are not an error — a zero-event session simply derives `custom`. See [the acp-agent example's sandbox variant](../../../examples/acp-agent/) for the composed leaf and [the sandbox RFC § Per-session modes](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md) for the switching design this layers over.
--- a/packages/ui/permission/package.json
+++ b/packages/ui/permission/package.json
@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-permission",
+  "description": "User-facing permission presets (ctx.permission) for the DeepSeek Harness: one product-level Permissions select bundling the sandbox-mode and approval-policy knobs, written through to their own session events",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-bash": "^0.0.1",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-user-approval": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-bash": "workspace:^",
+    "@deepseek-ai/dsh-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}
--- a/packages/ui/permission/src/index.ts
+++ b/packages/ui/permission/src/index.ts
@@ -0,0 +1,236 @@
+/**
+ * User-facing PERMISSION PRESETS: one product-level knob over the two
+ * mechanism knobs. A preset names a bundle — its sandbox mode
+ * (`bash/sandbox-mode`) and its approval policy (`approval/policy`) — so a
+ * user picks `request` or `yolo` where the mechanism tiers stay orthogonal
+ * capabilities. Switching a preset WRITES THROUGH: one `permission/preset` event
+ * records the chosen bundle (the audit fact reverse-mapping cannot recover —
+ * two presets may share knob values and differ only in composed policy, the
+ * planned `agent` preset being the standing example), then each knob event
+ * follows through its own THE-write-path setter, skipping values the session
+ * already effectively has. Every existing consumer (executor stamping, the
+ * approval gate, narrators, resume) keeps reading its own knob fold,
+ * untouched.
+ *
+ * @module dsh-permission
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from '@deepseek-ai/dsh-bash'
+import type { ApprovalPolicy } from '@deepseek-ai/dsh-user-approval'
+import { APPROVAL_POLICIES, effectiveApprovalPolicy, setApprovalPolicy } from '@deepseek-ai/dsh-user-approval'
+
+declare module 'cordis' {
+  interface Context {
+    permission: PermissionService
+  }
+}
+
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    /**
+     * The session's permission preset was switched — log-only (the
+     * `bash/sandbox-mode` precedent): durable and replayable, never in the
+     * model transcript. The LAST such event is the session's preset
+     * ({@link effectivePermissionPreset}); the knob events the switch wrote
+     * through follow it in the same turn, and they — not this record of the
+     * user's choice — are what execution reads.
+     */
+    'permission/preset': { preset: string }
+  }
+}
+
+/**
+ * One preset's knob bundle — the sandbox mode and approval policy a session
+ * runs under while the preset is active — plus its presentation.
+ */
+export interface PresetSpec {
+  /** The `bash/sandbox-mode` value the preset writes through. */
+  sandbox: SandboxMode
+  /** The `approval/policy` value the preset writes through. */
+  approval: ApprovalPolicy
+  /** The display label a client shows for this preset; the raw table key when omitted. */
+  name?: string
+  /** One user-facing sentence on what the preset means; omitted when not configured. */
+  description?: string
+}
+
+/** The select-option shape a presentation layer advertises for one preset (or for the derived `custom` state). */
+export interface PresetOption {
+  /** The machine value (`session/set_config_option` vocabulary): the table key, or `custom`. */
+  value: string
+  /** The display label. */
+  name: string
+  /** One user-facing sentence on what the value means. */
+  description?: string
+}
+
+/**
+ * The derived not-a-preset state: the session's effective knob values match
+ * no table entry (composition defaults outside the table, or a knob moved
+ * out from under the last-chosen preset). Never a switch target and never
+ * an event payload — {@link PermissionService.current} derives it, and the
+ * presentation layer shows it as a selectable-FROM-only current value.
+ */
+export const CUSTOM_PRESET = 'custom'
+
+/**
+ * The session's permission-preset override: the last `permission/preset` event in the
+ * log, or undefined when the session never switched (callers apply the
+ * plugin's configured default). The pure fold — resume needs no catch-up
+ * machinery because replaying the log IS the state.
+ * @param events - session events in log order (other event types are skipped).
+ * @returns the preset of the last switch event, or undefined without one.
+ */
+export function effectivePermissionPreset(events: readonly SessionEvent[]): string | undefined {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index] as SessionEvent
+    if (event.type === 'permission/preset') return event.data.preset
+  }
+  return undefined
+}
+
+/** The {@link PermissionService} config: the deployment's preset table. */
+export interface Config {
+  /**
+   * The preset table: name → knob bundle. Defaults to `request`
+   * (workspace-write + ask) and `yolo` (danger-full-access + never). The
+   * name `custom` is reserved for the derived not-a-preset state.
+   */
+  presets?: Record<string, PresetSpec>
+}
+
+/**
+ * The permission service (`ctx.permission`). Owns the deployment's preset
+ * table and THE write path for preset switches; presentation layers (the ACP
+ * bridge's single `Permissions` select) advertise {@link names} and call
+ * {@link set}. Composing it REQUIRES both mechanism knobs — a confining
+ * `ctx.bash` executor and the `ctx.approval` seam. A knob state matching no
+ * table entry is not an error but the derived {@link CUSTOM_PRESET} state:
+ * shown as the current value, never a switch target.
+ */
+export class PermissionService extends Service {
+  // Inline schema call: the config catalog walks `static Config` statically.
+  static Config: z<Config> = z.object({
+    presets: z.dict(z.object({
+      sandbox: z.union(SANDBOX_MODES as SandboxMode[]).required(),
+      approval: z.union(APPROVAL_POLICIES as ApprovalPolicy[]).required(),
+      name: z.string(),
+      description: z.string(),
+    })).default({
+      request: {
+        sandbox: 'workspace-write', approval: 'ask',
+        name: 'Request', description: 'Write inside the workspace; anything wider asks for your approval.',
+      },
+      yolo: {
+        sandbox: 'danger-full-access', approval: 'never',
+        name: 'YOLO', description: 'Full file access, no approval prompts.',
+      },
+    }),
+  })
+
+  static inject = ['bash', 'approval']
+
+  private readonly presets: Record<string, PresetSpec>
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'permission')
+    // The schema defaulted the table — the cast records that runtime fact.
+    this.presets = config.presets as Record<string, PresetSpec>
+    if (CUSTOM_PRESET in this.presets) {
+      throw new Error(`permission: "${CUSTOM_PRESET}" is reserved for the derived not-a-preset state and cannot name a table entry`)
+    }
+    if (ctx.bash.sandboxMode === undefined) {
+      throw new Error('permission: the mounted bash executor does not confine (no sandboxMode) — presets bundle a sandbox mode, so composing this plugin over an unconfined executor is a misconfiguration')
+    }
+  }
+
+  /**
+   * The advertised preset names, in the preset table's declaration order.
+   * @returns every switchable preset name.
+   */
+  get names(): readonly string[] {
+    return Object.keys(this.presets)
+  }
+
+  /**
+   * The preset a session is on right now, derived from the EFFECTIVE knob
+   * values (fold ?? composition default per knob): the last-chosen preset
+   * when its bundle still matches (presets may share bundles — the fold
+   * breaks the tie), else the first table entry that matches, else
+   * {@link CUSTOM_PRESET} — a mismatch is a state, not an error.
+   * @param events - the session's events in log order.
+   * @returns the effective preset name, or `custom` when nothing matches.
+   */
+  current(events: readonly SessionEvent[]): string {
+    const sandbox = effectiveSandboxMode(events) ?? this.ctx.bash.sandboxMode
+    const approval = effectiveApprovalPolicy(events) ?? this.ctx.approval.config.policy ?? 'ask'
+    const matches = (spec: PresetSpec): boolean => spec.sandbox === sandbox && spec.approval === approval
+    const folded = effectivePermissionPreset(events)
+    if (folded !== undefined) {
+      const spec = this.presets[folded]
+      if (spec !== undefined && matches(spec)) return folded
+    }
+    for (const [name, spec] of Object.entries(this.presets)) {
+      if (matches(spec)) return name
+    }
+    return CUSTOM_PRESET
+  }
+
+  /**
+   * A preset's knob bundle, for consumers presenting or validating one.
+   * @param name - the preset name to resolve.
+   * @returns the bundle; throws on a name outside the table (fails loud —
+   *   an unvalidated caller handed the service an unknown preset).
+   */
+  resolve(name: string): PresetSpec {
+    const spec = this.presets[name]
+    if (spec === undefined) {
+      throw new Error(`permission: unknown preset "${name}" (known: ${Object.keys(this.presets).join(', ')})`)
+    }
+    return spec
+  }
+
+  /**
+   * The select-option presentation of one advertisable value: a table entry
+   * (label/description from its spec, the raw key standing in for a missing
+   * label) or the derived {@link CUSTOM_PRESET} with its fixed presentation.
+   * @param name - a table key, or `custom`.
+   * @returns the option a client renders; throws on any other name.
+   */
+  optionOf(name: string): PresetOption {
+    if (name === CUSTOM_PRESET) {
+      return { value: CUSTOM_PRESET, name: 'Custom', description: 'A hand-set knob combination outside the preset table.' }
+    }
+    const spec = this.resolve(name)
+    return { value: name, name: spec.name ?? name, ...spec.description !== undefined ? { description: spec.description } : {} }
+  }
+
+  /**
+   * THE write path for a preset switch: appends one `permission/preset` event when
+   * `name` differs from the session's current preset, then writes each knob
+   * through its own setter, skipping values the session already effectively
+   * has — a net-zero switch appends nothing (the log records switches, not
+   * select clicks).
+   * @param session - the session the switch belongs to.
+   * @param name - the preset to switch to (validated via {@link resolve}).
+   */
+  set(session: Session, name: string): void {
+    const spec = this.resolve(name)
+    if (this.current(session.events) !== name) {
+      session.append('permission/preset', { preset: name })
+    }
+    const events = session.events
+    if (spec.sandbox !== (effectiveSandboxMode(events) ?? this.ctx.bash.sandboxMode)) {
+      setSandboxMode(session, spec.sandbox)
+    }
+    if (spec.approval !== (effectiveApprovalPolicy(events) ?? this.ctx.approval.config.policy ?? 'ask')) {
+      setApprovalPolicy(session, spec.approval)
+    }
+  }
+}
+
+export default PermissionService
--- a/packages/ui/permission/tests/permission.spec.ts
+++ b/packages/ui/permission/tests/permission.spec.ts
@@ -0,0 +1,147 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { ApprovalPolicy } from '@deepseek-ai/dsh-user-approval'
+import PermissionService, { CUSTOM_PRESET, effectivePermissionPreset } from '@deepseek-ai/dsh-permission'
+import type { Config } from '@deepseek-ai/dsh-permission'
+
+/** Mount the service over stand-in bash/approval capabilities (the two facts it validates against). */
+async function mounted(options: {
+  config?: Config
+  bashDefault?: SandboxMode | undefined
+  approvalDefault?: ApprovalPolicy | undefined
+} = {}): Promise<Context> {
+  const ctx = new Context()
+  ctx.provide('bash', { sandboxMode: 'bashDefault' in options ? options.bashDefault : 'workspace-write' })
+  ctx.provide('approval', { config: { policy: 'approvalDefault' in options ? options.approvalDefault : 'ask' } })
+  await ctx.plugin(PermissionService, options.config ?? {})
+  return ctx
+}
+
+/** A real Session seeded with one opened turn (events append without ceremony in unit scope). */
+function freshSession(id: string): Session {
+  return new Session(SessionId(id))
+}
+
+describe('effectivePermissionPreset', () => {
+  it('folds to the last event, or undefined without one', () => {
+    const session = freshSession('sess-fold')
+    expect(effectivePermissionPreset(session.events)).toBeUndefined()
+    session.append('permission/preset', { preset: 'yolo' })
+    session.append('permission/preset', { preset: 'request' })
+    expect(effectivePermissionPreset(session.events)).toBe('request')
+  })
+})
+
+describe('PermissionService', () => {
+  it('advertises the preset table in declaration order and resolves bundles', async () => {
+    const ctx = await mounted()
+    expect(ctx.permission.names).toEqual(['request', 'yolo'])
+    expect(ctx.permission.resolve('yolo')).toMatchObject({ sandbox: 'danger-full-access', approval: 'never' })
+    expect(() => ctx.permission.resolve('plan')).toThrow(/unknown preset "plan"/)
+  })
+
+  it('current() derives from the effective knobs: composition defaults hit request, a switch hits its preset', async () => {
+    const ctx = await mounted()
+    const session = freshSession('sess-current')
+    expect(ctx.permission.current(session.events)).toBe('request')
+    ctx.permission.set(session, 'yolo')
+    expect(ctx.permission.current(session.events)).toBe('yolo')
+  })
+
+  it('a knob state matching no table entry derives custom — a state, not an error', async () => {
+    const ctx = await mounted()
+    const session = freshSession('sess-custom')
+    session.append('bash/sandbox-mode', { mode: 'read-only' })
+    expect(ctx.permission.current(session.events)).toBe(CUSTOM_PRESET)
+    // Switching FROM custom is an ordinary write-through; custom itself is
+    // never a target.
+    ctx.permission.set(session, 'yolo')
+    expect(ctx.permission.current(session.events)).toBe('yolo')
+    expect(() => ctx.permission.resolve(CUSTOM_PRESET)).toThrow(/unknown preset/)
+  })
+
+  it('composition defaults outside the table derive custom at zero events', async () => {
+    const ctx = await mounted({ approvalDefault: 'never' })
+    const session = freshSession('sess-defaults-custom')
+    expect(ctx.permission.current(session.events)).toBe(CUSTOM_PRESET)
+  })
+
+  it('the fold breaks bundle ties; a stale fold no longer matching falls back to table order', async () => {
+    const ctx = await mounted({ config: { presets: {
+      request: { sandbox: 'workspace-write', approval: 'ask' },
+      agentish: { sandbox: 'workspace-write', approval: 'ask' },
+      yolo: { sandbox: 'danger-full-access', approval: 'never' },
+    } } })
+    const session = freshSession('sess-tie')
+    // Same bundle as request, chosen explicitly: the fold names it.
+    ctx.permission.set(session, 'agentish')
+    expect(ctx.permission.current(session.events)).toBe('agentish')
+    // A knob drifts: the fold's bundle no longer matches → reverse map wins.
+    session.append('approval/policy', { policy: 'never' })
+    session.append('bash/sandbox-mode', { mode: 'danger-full-access' })
+    expect(ctx.permission.current(session.events)).toBe('yolo')
+  })
+
+  it('set() writes through: one preset event plus both knob events', async () => {
+    const ctx = await mounted()
+    const session = freshSession('sess-set')
+    ctx.permission.set(session, 'yolo')
+    expect(session.events.map(e => [e.type, e.data])).toEqual([
+      ['permission/preset', { preset: 'yolo' }],
+      ['bash/sandbox-mode', { mode: 'danger-full-access' }],
+      ['approval/policy', { policy: 'never' }],
+    ])
+  })
+
+  it('set() to the current preset is a no-op when the knobs already match (clicks are not switches)', async () => {
+    const ctx = await mounted()
+    const session = freshSession('sess-noop')
+    ctx.permission.set(session, 'request')
+    expect(session.events).toHaveLength(0)
+  })
+
+  it('re-asserting a preset from a drifted (custom) state re-records the choice and repairs the knob', async () => {
+    const ctx = await mounted()
+    const session = freshSession('sess-drift')
+    ctx.permission.set(session, 'yolo')
+    // A knob drifts out from under the preset (a direct setter call, a test
+    // scenario): the session derives custom, and re-asserting the preset is
+    // a real switch again — choice re-recorded, only the drifted knob moves.
+    session.append('bash/sandbox-mode', { mode: 'read-only' })
+    ctx.permission.set(session, 'yolo')
+    const tail = session.events.slice(4)
+    expect(tail.map(e => [e.type, e.data])).toEqual([
+      ['permission/preset', { preset: 'yolo' }],
+      ['bash/sandbox-mode', { mode: 'danger-full-access' }],
+    ])
+  })
+
+  it('rejects composition over a non-confining executor at load', async () => {
+    await expect(mounted({ bashDefault: undefined }))
+      .rejects.toThrow(/does not confine/)
+  })
+
+  it('optionOf() presents shipped labels/descriptions, falls back to the raw key, and fixes custom', async () => {
+    const ctx = await mounted()
+    expect(ctx.permission.optionOf('yolo')).toEqual({ value: 'yolo', name: 'YOLO', description: 'Full file access, no approval prompts.' })
+    expect(ctx.permission.optionOf('custom')).toEqual({ value: 'custom', name: 'Custom', description: 'A hand-set knob combination outside the preset table.' })
+    const bare = await mounted({ config: { presets: { plain: { sandbox: 'workspace-write', approval: 'ask' } } } })
+    expect(bare.permission.optionOf('plain')).toEqual({ value: 'plain', name: 'plain' })
+    expect(() => ctx.permission.optionOf('plan')).toThrow(/unknown preset/)
+  })
+
+  it('rejects a table entry named custom (reserved for the derived state)', async () => {
+    await expect(mounted({ config: { presets: { custom: { sandbox: 'read-only', approval: 'ask' } } } }))
+      .rejects.toThrow(/reserved for the derived not-a-preset state/)
+  })
+
+  it('reads a schema-less approval stand-in as the ask default', async () => {
+    const ctx = await mounted({ approvalDefault: undefined })
+    const session = freshSession('sess-standin')
+    ctx.permission.set(session, 'request')
+    expect(session.events).toHaveLength(0)
+    expect(ctx.permission.current(session.events)).toBe('request')
+  })
+})
--- a/packages/ui/permission/tsconfig.json
+++ b/packages/ui/permission/tsconfig.json
@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../sandbox/sandbox"
+    },
+    {
+      "path": "../../bash/bash"
+    },
+    {
+      "path": "../user-approval"
+    }
+  ]
+}