Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

19.7 KB
Raw Blame
/**
 * Sandbox settings, as a settings group: the confinement every agent command spawns under is
 * declared on `PluginConfigProvider.groups` like any module's settings, drawn on the Settings
 * dialog's Plugins page and stored under `plugin-config:sandbox`, so a restart keeps it. A
 * sandbox backend that has settings of its own declares its own group with `parent: "sandbox"`
 * and reads it itself; nothing here carries a backend's values.
 *
 * `SandboxSettings` declares the group and applies what is stored to the service — on boot
 * and after every save. The service stays on the capability-free floor (a bare kernel boots
 * it with no database), and its parked context still carries the settings across a hot swap:
 * on boot a saved document wins, and with none saved the service keeps what the swap carried.
 * The card's live status (what this machine enforces, which backends are not in use and why)
 * is `SandboxSettingsStatus`, in settings-status.ts.
 */
import { Bind, Component, Use } from "@adelie/core/kernel";
import type { SandboxMode, SandboxSettings as Policy } from "@adelie/core/plugin";
import type { PluginConfigNotice } from "../api/types.js";
import { PluginConfig } from "../plugin/config.js";
import { Sandbox, SandboxModule } from "./service.js";
import { sandboxStartOf } from "./settings-policy.js";

/** The sandbox's group name (its contribution id), and the parent a backend's group names. */
export const SANDBOX_GROUP = "sandbox";

@Component({
  contributes: {
    "PluginConfigProvider.groups": [
      {
        id: "sandbox",
        order: 0,
        title: "Sandbox",
        titleZh: "沙盒",
        description:
          "The confinement new sessions start with, enforced by a sandbox backend plugin. A session keeps the policy it started with; change it from that session's permission button.",
        descriptionZh:
          "新建会话的初始封禁策略,由沙盒后端插件实施。已有会话保留创建时的策略,可在该会话的权限按钮中修改。",
        // Off, the card shows the switch alone: the presets, notices and backends' own settings
        // matter only to a confined Session.
        switch: "enabled",
        properties: {
          // No default: a document saved before the switch derives it (sandboxEnabledOf), and
          // with nothing saved that reads as off, the default mode being Off.
          enabled: {
            type: "boolean",
            title: "Enable",
            titleZh: "启用",
            description:
              "Whether new sessions start in the sandbox. On: from the default preset. Off: with full file and network access, held only by their ask mode. Sessions that already exist keep their own policy.",
            descriptionZh:
              "新会话是否进入沙盒。打开:从默认预设开始。关闭:拥有完全的文件与网络访问,只受询问模式约束。已有会话保留各自的策略。",
          },
          // The composer's menu: each preset a named mode, network level and approval mode, and
          // the default (marked after its name): the row a new Session starts from while on.
          // Full Access keeps its promise (nothing confined, everything approved): only its
          // name, whether the menu lists it and whether it is the default can change.
          presets: {
            type: "table",
            title: "Presets",
            titleZh: "预设",
            description:
              "Named combinations of file access, network and ask mode. The pinned ones are what the composer's permission menu offers, and the one marked (Default) is what a new session starts from while the sandbox is on; changing it reaches new sessions only. A session keeps its own three values, and the menu names it by the first row that matches. Each name's \"?\" says what the row is for.",
            descriptionZh:
              "文件访问、网络与询问模式的命名组合。固定的行出现在输入框的权限菜单里;沙盒打开时,新会话从标有(默认)的行开始,改动只影响此后新建的会话。会话只保存自己的三项取值,菜单按第一个匹配的行为它命名。每个名称旁的「?」说明这一行的用途。",
            rowChoice: { field: "defaultPreset", title: "Default", titleZh: "默认" },
            columnGroup: {
              title: "Action",
              titleZh: "操作",
              description:
                "Pin: listed in the composer's permission menu. Handle: drag to reorder (or focus it and use the arrow keys); the order is the menu's. …: set the row as the default, or delete a preset you added (built-in ones can only be unpinned).",
              descriptionZh:
                "图钉:列在输入框的权限菜单里。手柄:拖动调整顺序(或聚焦后按上下方向键),菜单按此顺序列出。…:设为默认,或删除你新增的预设(内置预设只能取消固定)。",
              columns: ["enabled"],
            },
            // Presets an administrator adds: only those can be deleted; every row can be moved,
            // and the order is the composer's menu order.
            extensible: {
              add: "Add preset",
              addZh: "添加预设",
              values: {
                name: "New preset",
                enabled: false,
                mode: "workspace-write",
                network: "open",
                approvalMode: "always-ask",
              },
              valuesZh: { name: "新预设" },
            },
            pin: {
              column: "enabled",
              on: "Pinned to the menu",
              onZh: "已固定到菜单",
              off: "Not in the menu",
              offZh: "不在菜单中",
            },
            columns: [
              {
                name: "name",
                type: "string",
                title: "Name",
                titleZh: "名称",
                description:
                  "What the menu and the permission button call this row. A rename keeps what the row does; clear the box to restore the original name.",
                descriptionZh:
                  "菜单与权限按钮显示的名称。改名不改变该行的作用;清空输入框即恢复原名。",
              },
              {
                name: "mode",
                type: "enum",
                title: "Files",
                titleZh: "文件",
                description:
                  "What a confined command may write. Full access: anywhere. Workspace: the session's workspace, its scratchpad and the temp directory. Read-only: the temp directory only. Needs a sandbox backend unless Full access.",
                descriptionZh:
                  "被封禁的命令能写哪里。完全访问:任何位置。仅工作区:会话的工作区、scratchpad 与临时目录。只读:只有临时目录。除「完全访问」外都需要沙盒后端。",
                options: [
                  {
                    value: "danger-full-access",
                    title: "Full access",
                    titleZh: "完全访问",
                    description: "Commands and file tools may write anywhere.",
                    descriptionZh: "命令与文件工具可以写任何位置。",
                  },
                  {
                    value: "workspace-write",
                    title: "Workspace write only",
                    titleZh: "仅工作区可写",
                    description:
                      "Commands and file tools may write only the workspace, the session's scratchpad and the temp directory.",
                    descriptionZh: "命令与文件工具只能写工作区、会话的 scratchpad 与临时目录。",
                  },
                  {
                    value: "read-only",
                    title: "Read-only",
                    titleZh: "只读",
                    description:
                      "Commands and file tools may write nothing but the temp directory.",
                    descriptionZh: "命令与文件工具除临时目录外什么都不能写。",
                  },
                ],
              },
              {
                name: "network",
                type: "enum",
                title: "Network",
                titleZh: "网络",
                description:
                  "What a confined command, hook script or read_file URL may reach. Localhost allows only this machine. Each limit needs a backend that can enforce it — sandbox-dsh confines files only — and is greyed out where the backends in use cannot.",
                descriptionZh:
                  "被封禁的命令、钩子脚本与 read_file 的 URL 能访问的网络。仅本机只允许访问本机。每种限制都需要能实施它的后端(sandbox-dsh 只封禁文件),在用的后端不能实施时显示为灰色。",
                options: [
                  {
                    value: "open",
                    title: "Full access",
                    titleZh: "完全访问",
                    description: "Any address can be reached.",
                    descriptionZh: "可以访问任何地址。",
                  },
                  {
                    value: "local",
                    title: "Localhost only",
                    titleZh: "仅本机",
                    description: "Only this machine can be reached.",
                    descriptionZh: "只能访问本机。",
                  },
                  {
                    value: "none",
                    title: "No network",
                    titleZh: "无网络",
                    description: "Nothing can be reached.",
                    descriptionZh: "无法访问任何网络。",
                  },
                ],
              },
              {
                name: "approvalMode",
                type: "enum",
                title: "Ask mode",
                titleZh: "询问模式",
                description:
                  "Which tool calls run without asking: all of them, only the ones that read, none (each asks first), or none at all (every call is denied).",
                descriptionZh:
                  "哪些工具调用无需询问即可执行:全部、仅读取类、都要先询问,或全部拒绝。",
                options: [
                  {
                    value: "allow-all",
                    title: "Approve everything",
                    titleZh: "全部批准",
                    description: "Every tool call runs without asking.",
                    descriptionZh: "每个工具调用都直接执行,不询问。",
                  },
                  {
                    value: "read-only",
                    title: "Approve read-only",
                    titleZh: "批准只读",
                    description: "Calls that only read run; every other call asks you first.",
                    descriptionZh: "只读的调用直接执行,其余调用先询问你。",
                  },
                  {
                    value: "always-ask",
                    title: "Ask every time",
                    titleZh: "每次询问",
                    description: "Every tool call asks you first.",
                    descriptionZh: "每个工具调用都先询问你。",
                  },
                  {
                    value: "deny-all",
                    title: "Deny everything",
                    titleZh: "全部拒绝",
                    description: "Every tool call is refused.",
                    descriptionZh: "每个工具调用都被拒绝。",
                  },
                ],
              },
              {
                name: "enabled",
                type: "boolean",
                title: "Pin",
                titleZh: "固定",
                description:
                  "Whether the composer's permission menu lists this row. An unpinned row can still be the default.",
                descriptionZh: "权限菜单是否列出这一行。未固定的行仍可作为默认。",
              },
            ],
            rows: [
              {
                id: "full-access",
                values: {
                  name: "Full Access",
                  enabled: true,
                  mode: "danger-full-access",
                  network: "open",
                  approvalMode: "allow-all",
                },
                valuesZh: { name: "完全访问" },
                description:
                  "No sandbox and nothing asked: the agent writes files, runs commands and uses the network freely. For work you trust and watch.",
                descriptionZh:
                  "不进沙盒,也不询问:Agent 可以随意写文件、执行命令、联网。适合你信任并在旁照看的工作。",
                locked: ["mode", "network", "approvalMode"],
              },
              {
                id: "always-ask",
                values: {
                  name: "Always Ask",
                  enabled: true,
                  mode: "danger-full-access",
                  network: "open",
                  approvalMode: "always-ask",
                },
                valuesZh: { name: "每次询问" },
                description:
                  "No sandbox, but every tool call waits for your approval. For approving the work step by step.",
                descriptionZh: "不进沙盒,但每个工具调用都要等你批准。适合一步步审批。",
              },
              {
                id: "workspace-write",
                values: {
                  name: "Workspace Write",
                  enabled: true,
                  mode: "workspace-write",
                  network: "open",
                  approvalMode: "allow-all",
                },
                valuesZh: { name: "仅工作区可写" },
                description:
                  "Commands and file tools change files only inside the workspace; the network is open and calls run without asking. For everyday coding.",
                descriptionZh:
                  "命令与文件工具只能改工作区内的文件;网络不受限,调用无需询问。适合日常编码。",
              },
              {
                id: "read-only",
                values: {
                  name: "Read Only",
                  enabled: true,
                  mode: "read-only",
                  network: "open",
                  approvalMode: "allow-all",
                },
                valuesZh: { name: "只读" },
                description:
                  "Nothing can be written but the temp directory; the network is open and calls run without asking. For exploring, reviewing and answering questions.",
                descriptionZh:
                  "除临时目录外什么都不能写;网络不受限,调用无需询问。适合浏览代码、审阅与答疑。",
              },
              {
                id: "workspace-write-ask",
                values: {
                  name: "Workspace Write with Ask",
                  enabled: false,
                  mode: "workspace-write",
                  network: "open",
                  approvalMode: "always-ask",
                },
                valuesZh: { name: "仅工作区可写并询问" },
                description:
                  "Like Workspace Write, but every tool call asks you first. For careful edits.",
                descriptionZh: "与「仅工作区可写」相同,但每个工具调用都先询问你。适合谨慎的修改。",
              },
              {
                id: "denied-all",
                values: {
                  name: "Denied All",
                  enabled: false,
                  mode: "danger-full-access",
                  network: "open",
                  approvalMode: "deny-all",
                },
                valuesZh: { name: "全部拒绝" },
                description:
                  "Every tool call is refused, so the agent can only talk. For a conversation with no tool use.",
                descriptionZh: "每个工具调用都被拒绝,Agent 只能对话。适合不使用工具的纯对话。",
              },
            ],
          },
          // The row a new Session starts from while the switch is on, drawn only as the table's
          // "(Default)" marker. No declared default: the derive hook shows DEFAULT_PRESET, or for a
          // document stored before it the row giving that document's start, else none
          // (settings-policy.ts, prePresetStartOf).
          defaultPreset: {
            type: "enum",
            title: "Default preset",
            titleZh: "默认预设",
            options: [
              { value: "full-access", title: "Full Access", titleZh: "完全访问" },
              { value: "always-ask", title: "Always Ask", titleZh: "每次询问" },
              { value: "workspace-write", title: "Workspace Write", titleZh: "仅工作区可写" },
              { value: "read-only", title: "Read Only", titleZh: "只读" },
              {
                value: "workspace-write-ask",
                title: "Workspace Write with Ask",
                titleZh: "仅工作区可写并询问",
              },
              { value: "denied-all", title: "Denied All", titleZh: "全部拒绝" },
            ],
          },
          writableTemp: {
            type: "boolean",
            advanced: true,
            title: "Temporary directory writable",
            titleZh: "临时目录可写",
            description:
              "Confined commands, hook scripts and file tools may write the system temp directory, in either mode. Shells and most tools need one to start; off keeps it read-only too. Off needs a backend that can close it — sandbox-dsh cannot — and is greyed out where the backends in use cannot.",
            descriptionZh:
              "被封禁的命令、钩子脚本与文件工具在两种模式下都可以写系统临时目录。Shell 与大多数工具需要它才能启动;关闭后临时目录同样只读。关闭需要能关闭它的后端(sandbox-dsh 不能),在用的后端不能关闭时显示为灰色。",
            default: true,
          },
          maskPaths: {
            type: "list",
            advanced: true,
            title: "Masked paths",
            titleZh: "屏蔽路径",
            description:
              "Paths hidden from confined commands, hook scripts and file tools, reads included. Needs a backend that masks paths — sandbox-dsh does not: without one, every command is refused while any is listed.",
            descriptionZh:
              "对被封禁的命令、钩子脚本与文件工具隐藏的路径,读取也不例外。需要能屏蔽路径的后端(sandbox-dsh 不能):没有这样的后端时,只要列了路径,每条命令都会被拒绝。",
            hint: "One absolute path per line, at most 64.",
            hintZh: "每行一个绝对路径,最多 64 条。",
            maxItems: 64,
            // POSIX `/…`, Windows `C:\…` or `C:/…`, or a UNC `\\server\…`.
            pattern: "^(?:/|[A-Za-z]:[\\\\/]|\\\\\\\\)",
            patternErrorMessage: "must list absolute paths",
          },
        },
      },
    ],
  },
})
export class SandboxSettings {
  @Use() private readonly pluginConfig!: PluginConfig;
  @Use(SandboxModule) private readonly sandbox!: Sandbox;
  setup() {
    const { pluginConfig, sandbox } = this;
    // A saved document wins; with none saved the service keeps what the swap carried —
    // applying the defaults here would un-confine a deployment on every hot update.
    const schema = () => pluginConfig.schema(SANDBOX_GROUP);
    if (pluginConfig.saved(SANDBOX_GROUP)) {
      sandbox.configure(sandboxStartOf(schema(), pluginConfig.get(SANDBOX_GROUP)).policy);
    }
    pluginConfig.watch(SANDBOX_GROUP, (doc) =>
      sandbox.configure(sandboxStartOf(schema(), doc).policy),
    );
  }
}