@roll-agent/core 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/THIRD_PARTY_NOTICES.txt +112 -0
  2. package/dist/cli/chat/banner.d.ts +13 -0
  3. package/dist/cli/chat/banner.js +1 -1
  4. package/dist/cli/chat/ink/app.d.ts +4 -1
  5. package/dist/cli/chat/ink/app.js +1 -1
  6. package/dist/cli/chat/ink/banner-view.d.ts +15 -0
  7. package/dist/cli/chat/ink/banner-view.js +1 -0
  8. package/dist/cli/chat/ink/commands.d.ts +4 -12
  9. package/dist/cli/chat/ink/commands.js +1 -1
  10. package/dist/cli/chat/ink/history-from-messages.js +1 -1
  11. package/dist/cli/chat/ink/history-item.js +1 -1
  12. package/dist/cli/chat/ink/input-history.d.ts +2 -0
  13. package/dist/cli/chat/ink/input-history.js +1 -0
  14. package/dist/cli/chat/ink/line-buffer.d.ts +2 -0
  15. package/dist/cli/chat/ink/line-buffer.js +1 -1
  16. package/dist/cli/chat/ink/live-region.d.ts +2 -0
  17. package/dist/cli/chat/ink/live-region.js +1 -1
  18. package/dist/cli/chat/ink/reasoning-block.d.ts +4 -0
  19. package/dist/cli/chat/ink/reasoning-block.js +1 -0
  20. package/dist/cli/chat/ink/run-ink-repl.js +1 -1
  21. package/dist/cli/chat/ink/spinner.d.ts +3 -1
  22. package/dist/cli/chat/ink/spinner.js +1 -1
  23. package/dist/cli/chat/ink/state.d.ts +26 -3
  24. package/dist/cli/chat/ink/state.js +1 -1
  25. package/dist/cli/chat/ink/text-prompt.d.ts +3 -1
  26. package/dist/cli/chat/ink/text-prompt.js +1 -1
  27. package/dist/cli/chat/ink/turn-activity.d.ts +19 -0
  28. package/dist/cli/chat/ink/turn-activity.js +1 -0
  29. package/dist/cli/chat/ink/turn-status-line.d.ts +14 -0
  30. package/dist/cli/chat/ink/turn-status-line.js +1 -0
  31. package/dist/cli/chat/ink/use-session.js +1 -1
  32. package/dist/cli/commands/chat.d.ts +28 -0
  33. package/dist/cli/commands/chat.js +1 -1
  34. package/dist/cli/commands/config-explain.js +1 -1
  35. package/dist/cli/commands/config-setup.js +1 -1
  36. package/dist/cli/commands/config.js +1 -1
  37. package/dist/cli/commands/doctor.js +1 -1
  38. package/dist/cli/commands/ui.d.ts +30 -0
  39. package/dist/cli/commands/ui.js +1 -0
  40. package/dist/cli/index.js +1 -1
  41. package/dist/cli/utils/chat-renderer.js +1 -1
  42. package/dist/cli/utils/current-cli-shim.d.ts +14 -0
  43. package/dist/cli/utils/current-cli-shim.js +1 -0
  44. package/dist/cli/utils/debug-format.d.ts +4 -0
  45. package/dist/cli/utils/debug-format.js +1 -0
  46. package/dist/config/application-service.d.ts +90 -0
  47. package/dist/config/application-service.js +1 -0
  48. package/dist/config/catalog.d.ts +76 -0
  49. package/dist/config/catalog.js +1 -0
  50. package/dist/config/defaults.d.ts +4 -3
  51. package/dist/config/defaults.js +1 -1
  52. package/dist/config/document-store.d.ts +70 -0
  53. package/dist/config/document-store.js +1 -0
  54. package/dist/config/guidance.d.ts +571 -0
  55. package/dist/config/guidance.js +1 -0
  56. package/dist/config/index.d.ts +6 -0
  57. package/dist/config/index.js +1 -1
  58. package/dist/config/key-codec.d.ts +24 -3
  59. package/dist/config/key-codec.js +1 -1
  60. package/dist/config/migration.js +1 -1
  61. package/dist/config/schema.d.ts +52 -7
  62. package/dist/config/schema.js +1 -1
  63. package/dist/config/secret-policy.d.ts +20 -0
  64. package/dist/config/secret-policy.js +1 -0
  65. package/dist/llm/providers.d.ts +8 -4
  66. package/dist/llm/providers.js +1 -1
  67. package/dist/registry/agent-lifecycle.d.ts +97 -0
  68. package/dist/registry/agent-lifecycle.js +1 -0
  69. package/dist/registry/discovery.js +1 -1
  70. package/dist/registry/install.js +1 -1
  71. package/dist/registry/process-identity.d.ts +14 -0
  72. package/dist/registry/process-identity.js +1 -0
  73. package/dist/registry/process-manager.d.ts +28 -7
  74. package/dist/registry/process-manager.js +1 -1
  75. package/dist/registry/store.js +1 -1
  76. package/dist/skills/invocation.d.ts +27 -0
  77. package/dist/skills/invocation.js +1 -0
  78. package/dist/types/agent.d.ts +6 -0
  79. package/dist/types/agent.js +1 -1
  80. package/dist/types/chat.d.ts +3 -0
  81. package/dist/ui/config-controller.d.ts +15 -0
  82. package/dist/ui/config-controller.js +1 -0
  83. package/dist/ui/contracts.d.ts +49 -0
  84. package/dist/ui/contracts.js +1 -0
  85. package/dist/ui/index.d.ts +8 -0
  86. package/dist/ui/index.js +1 -0
  87. package/dist/ui/runtime-controller.d.ts +38 -0
  88. package/dist/ui/runtime-controller.js +1 -0
  89. package/dist/ui/server.d.ts +21 -0
  90. package/dist/ui/server.js +1 -0
  91. package/dist/ui/static-assets.d.ts +2 -0
  92. package/dist/ui/static-assets.js +1 -0
  93. package/dist/ui-assets/assets/app.css +1 -0
  94. package/dist/ui-assets/assets/app.js +53 -0
  95. package/dist/ui-assets/assets/roll-mark-wXIkY5y0.svg +5 -0
  96. package/dist/ui-assets/index.html +17 -0
  97. package/package.json +16 -8
  98. package/dist/cli/commands/config-guidance.d.ts +0 -148
  99. package/dist/cli/commands/config-guidance.js +0 -1
package/dist/ui-assets/assets/roll-mark-wXIkY5y0.svg ADDED
@@ -0,0 +1,5 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
2
+ <rect width="64" height="64" rx="8" fill="#09090b" />
3
+ <rect x="10" y="10" width="44" height="44" rx="6" fill="#ff5e00" />
4
+ <path d="M23 20h12c8 0 13 4 13 11 0 5-3 9-8 10l9 11H39l-7-10h-1v10h-8V20Zm8 7v8h4c3 0 5-1 5-4s-2-4-5-4h-4Z" fill="#050506" />
5
+ </svg>
package/dist/ui-assets/index.html ADDED
@@ -0,0 +1,17 @@
1
+ <!doctype html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <meta name="color-scheme" content="dark" />
7
+ <meta name="theme-color" content="#09090b" />
8
+ <meta name="description" content="Roll 本地配置控制台：编辑、验证并应用 roll.config.yaml。" />
9
+ <link rel="icon" href="./assets/roll-mark-wXIkY5y0.svg" type="image/svg+xml" />
10
+ <title>Roll / Local Control</title>
11
+ <script type="module" crossorigin src="./assets/app.js"></script>
12
+ <link rel="stylesheet" crossorigin href="./assets/app.css">
13
+ </head>
14
+ <body>
15
+ <div id="root"></div>
16
+ </body>
17
+ </html>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@roll-agent/core",
3
- "version": "0.18.0",
3
+ "version": "0.20.0",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
@@ -56,7 +56,8 @@
56
56
  },
57
57
  "files": [
58
58
  "dist",
59
- "bin"
59
+ "bin",
60
+ "THIRD_PARTY_NOTICES.txt"
60
61
  ],
61
62
  "engines": {
62
63
  "node": ">=22.6.0"
@@ -67,6 +68,7 @@
67
68
  "@ai-sdk/deepseek": "^3.0.2",
68
69
  "@ai-sdk/openai": "^4.0.4",
69
70
  "@ai-sdk/provider": "^4.0.1",
71
+ "@ai-sdk/xai": "4.0.12",
70
72
  "@clack/prompts": "1.4.0",
71
73
  "@modelcontextprotocol/sdk": "^1.12.0",
72
74
  "ai": "^7.0.9",
@@ -83,19 +85,25 @@
83
85
  "string-width": "8.2.1",
84
86
  "yaml": "^2.7.0",
85
87
  "zod": "^3.25.76",
86
- "@roll-agent/runtime": "0.7.0"
88
+ "@roll-agent/runtime": "0.8.0"
87
89
  },
88
90
  "devDependencies": {
91
+ "@tailwindcss/vite": "4.3.2",
89
92
  "@types/cross-spawn": "6.0.6",
90
93
  "@types/node": "^22.0.0",
91
- "@types/react": "19.2.16",
92
- "ink-testing-library": "4.0.0"
94
+ "@types/react": "19.2.17",
95
+ "@types/react-dom": "19.2.3",
96
+ "@vitejs/plugin-react": "4.7.0",
97
+ "ink-testing-library": "4.0.0",
98
+ "react-dom": "19.2.7",
99
+ "tailwindcss": "4.3.2",
100
+ "vite": "6.4.3"
93
101
  },
94
102
  "scripts": {
95
103
  "dev": "node --disable-warning=ExperimentalWarning --experimental-strip-types --experimental-sqlite src/cli/index.ts",
96
- "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/obfuscate.mjs",
97
- "typecheck": "tsc --noEmit",
98
- "test": "node --experimental-strip-types --experimental-sqlite --test \"src/**/*.test.ts\"",
104
+ "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/obfuscate.mjs && vite build --config vite.config.ts",
105
+ "typecheck": "tsc --noEmit && tsc -p tsconfig.ui.json",
106
+ "test": "node --experimental-strip-types --experimental-sqlite --test \"src/**/*.test.ts\" \"ui/**/*.test.ts\"",
99
107
  "test:e2e": "node --experimental-strip-types --experimental-sqlite --test \"src/**/*.e2e.ts\"",
100
108
  "clean": "rm -rf dist"
101
109
  }
package/dist/cli/commands/config-guidance.d.ts DELETED
@@ -1,148 +0,0 @@
1
- import type { AgentEnvDeclaration, AgentSkillEnvDeclarations } from "../../types/agent.ts";
2
- export declare const INSTALL_SCENARIOS: readonly ["default-network", "china-dev", "private-registry", "advanced"];
3
- export type InstallScenario = (typeof INSTALL_SCENARIOS)[number];
4
- export interface ConfigGuidanceEntry {
5
- readonly path: string;
6
- readonly title: string;
7
- readonly purpose: string;
8
- readonly defaultBehavior?: string;
9
- readonly example?: string;
10
- readonly setupCommand?: string;
11
- }
12
- export declare const CONFIG_GUIDANCE_ENTRIES: readonly [{
13
- readonly path: "llm.default-provider";
14
- readonly title: "默认 LLM Provider";
15
- readonly purpose: "`roll ask` / `roll chat` 默认使用的模型提供商。";
16
- readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\u3002`;
17
- readonly example: `llm:
18
- default-provider: ${string}`;
19
- readonly setupCommand: "roll config setup llm";
20
- }, {
21
- readonly path: "llm.default-model";
22
- readonly title: "默认 LLM Model";
23
- readonly purpose: "`roll ask` / `roll chat` 默认使用的模型名称。";
24
- readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\u3002`;
25
- readonly example: `llm:
26
- default-model: ${string}`;
27
- readonly setupCommand: "roll config setup llm";
28
- }, {
29
- readonly path: "llm.providers.<provider>.api-key";
30
- readonly title: "Provider API Key";
31
- readonly purpose: string;
32
- readonly example: string;
33
- readonly setupCommand: "roll config setup llm";
34
- }, {
35
- readonly path: "llm.providers.<provider>.base-url";
36
- readonly title: "Provider Base URL";
37
- readonly purpose: "指定 LLM provider 的自定义 API base URL，通常只在代理、兼容网关或私有部署时需要。";
38
- readonly defaultBehavior: "不配置时使用 provider SDK 默认地址。";
39
- readonly example: "llm:\n providers:\n openai:\n base-url: https://api.openai.com/v1";
40
- readonly setupCommand: "roll config setup llm";
41
- }, {
42
- readonly path: "install.registry";
43
- readonly title: "npm Registry";
44
- readonly purpose: "`roll agent install` / `roll update` 查询和安装 npm 包时使用的 registry。";
45
- readonly defaultBehavior: "不配置时走 npm 自身默认源；Roll 不做隐式镜像 fallback。";
46
- readonly example: "install:\n registry: https://registry.npmmirror.com";
47
- readonly setupCommand: "roll config setup install";
48
- }, {
49
- readonly path: "install.fetch-retries";
50
- readonly title: "npm Fetch Retries";
51
- readonly purpose: "透传给 npm 的 `--fetch-retries`，同时影响 Roll 层整体网络重试次数。";
52
- readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\u3002`;
53
- readonly example: `install:
54
- fetch-retries: ${number}`;
55
- readonly setupCommand: "roll config setup install";
56
- }, {
57
- readonly path: "install.prefer-offline";
58
- readonly title: "Prefer Offline";
59
- readonly purpose: "安装时是否附加 `--prefer-offline`。";
60
- readonly defaultBehavior: "默认值为 `false`，避免更新时复用过期 npm 元数据。" | "默认值为 `true`，避免更新时复用过期 npm 元数据。";
61
- readonly example: "install:\n prefer-offline: false" | "install:\n prefer-offline: true";
62
- readonly setupCommand: "roll config setup install";
63
- }, {
64
- readonly path: "install.network-timeout-ms";
65
- readonly title: "Install Network Timeout";
66
- readonly purpose: "单次 npm install 命令的超时时间，单位毫秒。";
67
- readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\uFF0C\u5373 120 \u79D2\u3002`;
68
- readonly example: `install:
69
- network-timeout-ms: ${number}`;
70
- readonly setupCommand: "roll config setup install";
71
- }, {
72
- readonly path: "agents.data-dir";
73
- readonly title: "Agent 数据目录";
74
- readonly purpose: "Roll 持久化已注册 Agent、PID、日志和 runtime sidecar 的目录。";
75
- readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\u3002`;
76
- readonly example: `agents:
77
- data-dir: ${string}`;
78
- }, {
79
- readonly path: "agents.env.<agent-name>";
80
- readonly title: "Agent 环境变量";
81
- readonly purpose: "按 Agent 名称声明注入到子 Agent 进程的环境变量。";
82
- readonly defaultBehavior: "未配置时只会继承当前 shell 环境变量；core-managed Agent 需要重启才会看到新值。";
83
- readonly example: "agents:\n env:\n browser-use-agent:\n REPLY_AUTHORITY_URL: https://example.com";
84
- readonly setupCommand: "roll config setup agent <agent-name>";
85
- }, {
86
- readonly path: "ask.confirm-threshold";
87
- readonly title: "Ask 确认阈值";
88
- readonly purpose: "`roll ask` 路由置信度低于该阈值时，倾向要求用户确认。";
89
- readonly defaultBehavior: "未配置时使用内置路由默认行为。";
90
- readonly example: "ask:\n confirm-threshold: 0.5";
91
- }, {
92
- readonly path: "runtime.approval.default";
93
- readonly title: "Chat 工具确认默认策略";
94
- readonly purpose: "`roll chat` 调用工具时的默认确认策略。`guarded` 使用内置读写启发式，`auto` 默认放行非破坏性工具，`deny` 默认拒绝。";
95
- readonly defaultBehavior: "默认值为 `auto`。此配置不影响 `roll ask`。" | "默认值为 `guarded`。此配置不影响 `roll ask`。" | "默认值为 `deny`。此配置不影响 `roll ask`。";
96
- readonly example: "runtime:\n approval:\n default: auto" | "runtime:\n approval:\n default: guarded" | "runtime:\n approval:\n default: deny";
97
- }, {
98
- readonly path: "runtime.approval.overrides";
99
- readonly title: "Chat 工具确认精确覆盖";
100
- readonly purpose: "`roll chat` 按完整 `agentName.toolName` 覆盖单个工具的确认策略。可选值为 `auto`、`confirm`、`deny`。";
101
- readonly defaultBehavior: "未配置时回退到 `runtime.approval.default`。";
102
- readonly example: "runtime:\n approval:\n overrides:\n browser-use-agent.zhipin_send_prepared_reply: confirm\n browser-use-agent.browser_status: auto";
103
- }, {
104
- readonly path: "runtime.shell.enabled";
105
- readonly title: "Chat 内建 shell 工具";
106
- readonly purpose: "开启后 `roll chat` 注册内建 shell 工具：macOS/Linux 为 `roll__bash`，Windows 原生为 `roll__powershell`（需 PowerShell 7+）。命令继承 roll 进程环境变量；默认确认策略可由 `runtime.approval` 及精确 override 覆盖。";
107
- readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF08\u5173\u95ED\uFF09\u3002Windows \u672A\u68C0\u6D4B\u5230 pwsh 7+ \u65F6\u4F1A\u8DF3\u8FC7\u6CE8\u518C\u3002`;
108
- readonly example: "runtime:\n shell:\n enabled: true";
109
- readonly setupCommand: "roll config setup shell";
110
- }, {
111
- readonly path: "runtime.shell.auto-approve-safe";
112
- readonly title: "只读命令免确认";
113
- readonly purpose: "开启后用内建规则分类器识别 POSIX known-safe 只读命令（如 `ls`、`cat`、`git status`），在 `guarded`/`auto` 策略下免确认执行；dangerous（`rm -rf`、`sudo`）与无法识别的命令默认仍需确认。工具级显式 approval override 优先；Windows PowerShell 当前全部按 unknown 处理。";
114
- readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\u3002\u5173\u95ED\u540E POSIX \u56DE\u5F52\u9ED8\u8BA4\u9010\u6761\u786E\u8BA4\uFF1BWindows PowerShell \u9ED8\u8BA4\u9010\u6761\u786E\u8BA4\uFF0C\u663E\u5F0F approval override \u53EF\u8986\u76D6\u3002`;
115
- readonly example: "runtime:\n shell:\n enabled: true\n auto-approve-safe: false";
116
- readonly setupCommand: "roll config setup shell";
117
- }, {
118
- readonly path: "runtime.shell.session.enabled";
119
- readonly title: "Chat 会话式长命令执行";
120
- readonly purpose: "开启后在 macOS/Linux POSIX shell 与 Windows PowerShell 7+ 后端注册 `roll__exec_command`、`roll__exec_poll`、`roll__exec_list` 工具：命令在后台会话执行、跨轮存活，模型可列出会话、轮询进度并读取退出码，适合超过单轮超时的长脚本。仅交互 REPL 与 `--server` 长驻模式注册（单条消息 / `--json` 单轮会话随进程结束，不提供这些工具）；`--server` 下 `exec_command` 需 `runtime.approval.overrides` 里 `roll.exec_command: auto` 显式授权。";
121
- readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF08\u5173\u95ED\uFF09\u3002\u9700\u540C\u65F6\u5F00\u542F runtime.shell.enabled\uFF1B\u80CC\u666F\u4F1A\u8BDD\u968F roll chat \u8FDB\u7A0B\u9000\u51FA\u800C\u7EC8\u6B62\u3002`;
122
- readonly example: "runtime:\n shell:\n enabled: true\n session:\n enabled: true\n approval:\n overrides:\n roll.exec_command: auto";
123
- readonly setupCommand: "roll config setup shell";
124
- }, {
125
- readonly path: "skills.dirs";
126
- readonly title: "Chat 额外 skill 目录";
127
- readonly purpose: "`roll chat` 除自动发现项目与用户级 `.agents/skills`（`npx skills add` 的标准安装位置）及已注册 Agent 的 SKILL.md 外，额外加载的 skill 目录。目录可以直接包含 SKILL.md，也可以是多个 skill 子目录的集合。";
128
- readonly defaultBehavior: "默认为空。标准路径 `<项目>/.agents/skills` 与 `~/.agents/skills` 始终自动发现。";
129
- readonly example: "skills:\n dirs:\n - ./openclaw-roll-core-skill-template";
130
- }, {
131
- readonly path: "browser.default-instance";
132
- readonly title: "默认浏览器实例";
133
- readonly purpose: "多浏览器实例配置下，未显式指定 browserInstance 时使用的默认实例。";
134
- readonly defaultBehavior: "不配置且只有一个实例时可自动推断；多个实例时工具可能返回 needs_input。";
135
- readonly example: "browser:\n default-instance: boss-a";
136
- }, {
137
- readonly path: "browser.instances";
138
- readonly title: "浏览器实例声明";
139
- readonly purpose: "声明 browser-use-agent 可使用的浏览器 profile、CDP 端口、会话目录和业务归因信息。";
140
- readonly defaultBehavior: "不配置时 browser-use-agent 使用 legacy 单实例环境变量路径。";
141
- readonly example: "browser:\n instances:\n boss-a:\n platform: zhipin\n mode: managed-cdp\n cdp-port: 9222\n user-data-dir: ~/.roll-agent/browser/boss-a";
142
- }];
143
- export declare function listConfigGuidanceEntries(): readonly ConfigGuidanceEntry[];
144
- export declare function findConfigGuidance(path: string): ConfigGuidanceEntry | undefined;
145
- export declare function flattenAgentEnvDeclarations(declarations: AgentSkillEnvDeclarations | undefined): ReadonlyArray<AgentEnvDeclaration & {
146
- readonly required: boolean;
147
- }>;
148
- export declare function isSecretEnvName(name: string): boolean;
package/dist/cli/commands/config-guidance.js DELETED
@@ -1 +0,0 @@
1
- import{DEFAULT_CONFIG as e}from"../../config/defaults.js";import{normalizeUserPath as l}from"../../config/key-codec.js";export const INSTALL_SCENARIOS=["default-network","china-dev","private-registry","advanced"];export const CONFIG_GUIDANCE_ENTRIES=[{path:"llm.default-provider",title:"默认 LLM Provider",purpose:"`roll ask` / `roll chat` 默认使用的模型提供商。",defaultBehavior:`默认值为 \`${e.llm.defaultProvider}\`。`,example:`llm:\n default-provider: ${e.llm.defaultProvider}`,setupCommand:"roll config setup llm"},{path:"llm.default-model",title:"默认 LLM Model",purpose:"`roll ask` / `roll chat` 默认使用的模型名称。",defaultBehavior:`默认值为 \`${e.llm.defaultModel}\`。`,example:`llm:\n default-model: ${e.llm.defaultModel}`,setupCommand:"roll config setup llm"},{path:"llm.providers.<provider>.api-key",title:"Provider API Key",purpose:"指定 LLM provider 的 API key。可以写真实 key，也可以写 `${ENV_VAR}` 占位符。",example:"llm:\n providers:\n anthropic:\n api-key: ${ANTHROPIC_API_KEY}",setupCommand:"roll config setup llm"},{path:"llm.providers.<provider>.base-url",title:"Provider Base URL",purpose:"指定 LLM provider 的自定义 API base URL，通常只在代理、兼容网关或私有部署时需要。",defaultBehavior:"不配置时使用 provider SDK 默认地址。",example:"llm:\n providers:\n openai:\n base-url: https://api.openai.com/v1",setupCommand:"roll config setup llm"},{path:"install.registry",title:"npm Registry",purpose:"`roll agent install` / `roll update` 查询和安装 npm 包时使用的 registry。",defaultBehavior:"不配置时走 npm 自身默认源；Roll 不做隐式镜像 fallback。",example:"install:\n registry: https://registry.npmmirror.com",setupCommand:"roll config setup install"},{path:"install.fetch-retries",title:"npm Fetch Retries",purpose:"透传给 npm 的 `--fetch-retries`，同时影响 Roll 层整体网络重试次数。",defaultBehavior:`默认值为 \`${e.install.fetchRetries}\`。`,example:`install:\n fetch-retries: ${e.install.fetchRetries}`,setupCommand:"roll config setup install"},{path:"install.prefer-offline",title:"Prefer Offline",purpose:"安装时是否附加 `--prefer-offline`。",defaultBehavior:`默认值为 \`${e.install.preferOffline}\`，避免更新时复用过期 npm 元数据。`,example:`install:\n prefer-offline: ${e.install.preferOffline}`,setupCommand:"roll config setup install"},{path:"install.network-timeout-ms",title:"Install Network Timeout",purpose:"单次 npm install 命令的超时时间，单位毫秒。",defaultBehavior:`默认值为 \`${e.install.networkTimeoutMs}\`，即 120 秒。`,example:`install:\n network-timeout-ms: ${e.install.networkTimeoutMs}`,setupCommand:"roll config setup install"},{path:"agents.data-dir",title:"Agent 数据目录",purpose:"Roll 持久化已注册 Agent、PID、日志和 runtime sidecar 的目录。",defaultBehavior:`默认值为 \`${e.agents.dataDir}\`。`,example:`agents:\n data-dir: ${e.agents.dataDir}`},{path:"agents.env.<agent-name>",title:"Agent 环境变量",purpose:"按 Agent 名称声明注入到子 Agent 进程的环境变量。",defaultBehavior:"未配置时只会继承当前 shell 环境变量；core-managed Agent 需要重启才会看到新值。",example:"agents:\n env:\n browser-use-agent:\n REPLY_AUTHORITY_URL: https://example.com",setupCommand:"roll config setup agent <agent-name>"},{path:"ask.confirm-threshold",title:"Ask 确认阈值",purpose:"`roll ask` 路由置信度低于该阈值时，倾向要求用户确认。",defaultBehavior:"未配置时使用内置路由默认行为。",example:"ask:\n confirm-threshold: 0.5"},{path:"runtime.approval.default",title:"Chat 工具确认默认策略",purpose:"`roll chat` 调用工具时的默认确认策略。`guarded` 使用内置读写启发式，`auto` 默认放行非破坏性工具，`deny` 默认拒绝。",defaultBehavior:`默认值为 \`${e.runtime.approval.default}\`。此配置不影响 \`roll ask\`。`,example:`runtime:\n approval:\n default: ${e.runtime.approval.default}`},{path:"runtime.approval.overrides",title:"Chat 工具确认精确覆盖",purpose:"`roll chat` 按完整 `agentName.toolName` 覆盖单个工具的确认策略。可选值为 `auto`、`confirm`、`deny`。",defaultBehavior:"未配置时回退到 `runtime.approval.default`。",example:"runtime:\n approval:\n overrides:\n browser-use-agent.zhipin_send_prepared_reply: confirm\n browser-use-agent.browser_status: auto"},{path:"runtime.shell.enabled",title:"Chat 内建 shell 工具",purpose:"开启后 `roll chat` 注册内建 shell 工具：macOS/Linux 为 `roll__bash`，Windows 原生为 `roll__powershell`（需 PowerShell 7+）。命令继承 roll 进程环境变量；默认确认策略可由 `runtime.approval` 及精确 override 覆盖。",defaultBehavior:`默认值为 \`${String(e.runtime.shell.enabled)}\`（关闭）。Windows 未检测到 pwsh 7+ 时会跳过注册。`,example:"runtime:\n shell:\n enabled: true",setupCommand:"roll config setup shell"},{path:"runtime.shell.auto-approve-safe",title:"只读命令免确认",purpose:"开启后用内建规则分类器识别 POSIX known-safe 只读命令（如 `ls`、`cat`、`git status`），在 `guarded`/`auto` 策略下免确认执行；dangerous（`rm -rf`、`sudo`）与无法识别的命令默认仍需确认。工具级显式 approval override 优先；Windows PowerShell 当前全部按 unknown 处理。",defaultBehavior:`默认值为 \`${String(e.runtime.shell.autoApproveSafe)}\`。关闭后 POSIX 回归默认逐条确认；Windows PowerShell 默认逐条确认，显式 approval override 可覆盖。`,example:"runtime:\n shell:\n enabled: true\n auto-approve-safe: false",setupCommand:"roll config setup shell"},{path:"runtime.shell.session.enabled",title:"Chat 会话式长命令执行",purpose:"开启后在 macOS/Linux POSIX shell 与 Windows PowerShell 7+ 后端注册 `roll__exec_command`、`roll__exec_poll`、`roll__exec_list` 工具：命令在后台会话执行、跨轮存活，模型可列出会话、轮询进度并读取退出码，适合超过单轮超时的长脚本。仅交互 REPL 与 `--server` 长驻模式注册（单条消息 / `--json` 单轮会话随进程结束，不提供这些工具）；`--server` 下 `exec_command` 需 `runtime.approval.overrides` 里 `roll.exec_command: auto` 显式授权。",defaultBehavior:`默认值为 \`${String(e.runtime.shell.session.enabled)}\`（关闭）。需同时开启 runtime.shell.enabled；背景会话随 roll chat 进程退出而终止。`,example:"runtime:\n shell:\n enabled: true\n session:\n enabled: true\n approval:\n overrides:\n roll.exec_command: auto",setupCommand:"roll config setup shell"},{path:"skills.dirs",title:"Chat 额外 skill 目录",purpose:"`roll chat` 除自动发现项目与用户级 `.agents/skills`（`npx skills add` 的标准安装位置）及已注册 Agent 的 SKILL.md 外，额外加载的 skill 目录。目录可以直接包含 SKILL.md，也可以是多个 skill 子目录的集合。",defaultBehavior:"默认为空。标准路径 `<项目>/.agents/skills` 与 `~/.agents/skills` 始终自动发现。",example:"skills:\n dirs:\n - ./openclaw-roll-core-skill-template"},{path:"browser.default-instance",title:"默认浏览器实例",purpose:"多浏览器实例配置下，未显式指定 browserInstance 时使用的默认实例。",defaultBehavior:"不配置且只有一个实例时可自动推断；多个实例时工具可能返回 needs_input。",example:"browser:\n default-instance: boss-a"},{path:"browser.instances",title:"浏览器实例声明",purpose:"声明 browser-use-agent 可使用的浏览器 profile、CDP 端口、会话目录和业务归因信息。",defaultBehavior:"不配置时 browser-use-agent 使用 legacy 单实例环境变量路径。",example:"browser:\n instances:\n boss-a:\n platform: zhipin\n mode: managed-cdp\n cdp-port: 9222\n user-data-dir: ~/.roll-agent/browser/boss-a"}];export function listConfigGuidanceEntries(){return CONFIG_GUIDANCE_ENTRIES}export function findConfigGuidance(e){const r=l(e.split(".")).join(".");return CONFIG_GUIDANCE_ENTRIES.find(e=>t(e.path,r))}function t(e,t){const r=l(e.split(".")).join(".");if(r===t)return!0;const a=r.split("."),n=t.split(".");return a.length===n.length&&a.every((e,l)=>e.startsWith("<")||e===n[l])}export function flattenAgentEnvDeclarations(e){return[...(e?.required??[]).map(e=>({...e,required:!0})),...(e?.optional??[]).map(e=>({...e,required:!1}))]}export function isSecretEnvName(e){return/(?:TOKEN|KEY|SECRET|PASSWORD)/iu.test(e)}