@echo-agent/coding 0.6.0 → 0.8.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.
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @echo-agent/coding
2
2
 
3
3
  Echo's coding agent: file, search, shell and web tools, as a product built from
4
- `@echo-agent/base` and `@echo-agent/tui`. Installs the `echo-coding` command.
4
+ `@echo-agent/base`, `@echo-agent/tools` and `@echo-agent/tui`. Installs the `echo-coding` command.
5
5
 
6
6
  > **Requires [Bun](https://bun.sh/).** The executable is TypeScript with a `#!/usr/bin/env bun`
7
7
  > shebang, and the package entry point is TypeScript source. Node is not supported for this
@@ -21,9 +21,21 @@ Or run it once without installing: `bunx --package @echo-agent/coding echo-codin
21
21
  The command name stays `echo-coding` even though the package is scoped — the unscoped name was
22
22
  already taken on npm by an unrelated project.
23
23
 
24
- `echo-coding` accepts the same options as `echo-agent` (`--help`). **It runs every tool without
25
- asking**, in the interactive UI and through a pipe alike — treat it as a script that may change
26
- files in the current directory.
24
+ `echo-coding` accepts the same options as `echo-agent` (`--help`). In the interactive UI, the
25
+ runtime's safety classifier checks every shell command, web fetch and any tool not known to be
26
+ safe (MCP and extension tools included) against what you asked for, before it runs: a one-word
27
+ quick check, and a careful second look only for what the quick check flags. You are asked only when
28
+ the classifier keeps blocking or cannot run. Shell commands run in an OS sandbox (macOS
29
+ `sandbox-exec`, Linux bubblewrap) that can write only inside the working directory, temporary
30
+ directories and package caches, and cannot read echo's credential file. Where no sandbox works
31
+ (inside most containers), each command has to run explicitly outside it and is checked the same
32
+ way. **Through a pipe it runs every tool without asking** — treat it there as a script that may
33
+ change files in the current directory.
34
+
35
+ Whether the classifier runs is your call: set `"safetyClassifier": false` (or `true`) in
36
+ `$ECHO_HOME/settings.json`. Unset, it is on in the interactive UI and off through a pipe; set, it
37
+ applies to both. With it off, the sandbox still applies in the interactive UI, and a command that
38
+ asks to run outside it asks you first.
27
39
 
28
40
  Sessions belong to a directory *and* a command, so `echo-agent` and `echo-coding` never share a
29
41
  conversation even in the same directory.
@@ -31,10 +43,11 @@ conversation even in the same directory.
31
43
  ## What this package is
32
44
 
33
45
  A **product**, not a framework layer. It owns its identity and conduct sections, its permission
34
- policy and the `echo:workspace`, `echo:shell`, `echo:worktree` and `echo:web` extensions; the
35
- launcher parts come from `@echo-agent/base` and the terminal shell from `@echo-agent/tui`. It does
36
- not depend on `echo-agent` — the two are siblings, which is exactly the path a third-party product
37
- would take on this runtime.
46
+ policy and the `echo:worktree` extension (git worktree isolation). The file, search, shell and web
47
+ tools are not its own: the `echo:workspace`, `echo:shell` and `echo:web` extensions come from
48
+ `@echo-agent/tools`, and this product mounts them. The launcher parts come from `@echo-agent/base`
49
+ and the terminal shell from `@echo-agent/tui`. It does not depend on `echo-agent` — the two are
50
+ siblings, which is exactly the path a third-party product would take on this runtime.
38
51
 
39
52
  Full documentation is in the
40
53
  [repository README](https://github.com/echo-yiyi/echo-agent#readme).
package/package.json CHANGED
@@ -1,16 +1,17 @@
1
1
  {
2
2
  "name": "@echo-agent/coding",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
- "description": "Echo's coding agent: file, search, shell and web tools, its own identity and conduct. Installs the `echo-coding` command. Requires Bun.",
6
+ "description": "Echo's coding agent: its own identity and conduct on top of the standard file, search, shell and web tools, plus git worktree isolation. Installs the `echo-coding` command. Requires Bun.",
7
7
  "bin": {
8
8
  "echo-coding": "./bin/echo-coding.ts"
9
9
  },
10
10
  "dependencies": {
11
- "@echo-agent/base": "0.6.0",
12
- "@echo-agent/core": "0.6.0",
13
- "@echo-agent/tui": "0.6.0"
11
+ "@echo-agent/base": "0.8.0",
12
+ "@echo-agent/core": "0.8.0",
13
+ "@echo-agent/tools": "0.8.0",
14
+ "@echo-agent/tui": "0.8.0"
14
15
  },
15
16
  "devDependencies": {
16
17
  "@types/bun": "latest",
package/src/agent.ts CHANGED
@@ -8,7 +8,7 @@
8
8
  // 更要命的是它会分家:`createEcho()` 后来补的每一条(inline 工具转 Extension、
9
9
  // 清单与真相相等、失败路径逆序卸载),这边都得再补一遍,漏一条就是两种行为。
10
10
  //
11
- // 现在这里只出**数据**:权限策略、三条 Extension 的 Entry(产品的 prompt 段也在其中)。
11
+ // 现在这里只出**数据**:权限策略、五条 Extension 的 Entry(产品的 prompt 段也在其中)。
12
12
  // 装配归 `createEcho()`,一处。
13
13
  //
14
14
  // ```ts
@@ -21,35 +21,53 @@
21
21
  // ```
22
22
  //
23
23
  // system prompt(2026-09-01):不再有 `systemPrompt` 字符串。产品的身份与编码纪律是 `echo:coding`
24
- // 这条 prompt pack 的两段;文件 / shell 工具的习惯段随 `echo:workspace` / `echo:shell` 走
25
- // (文本都在 `prompt.ts`)。工具目录不进 system。
24
+ // 这条 prompt pack 的两段(文本在 `prompt.ts`);文件 / shell 工具的习惯段随 `echo:workspace` / `echo:shell` 走
25
+ // (文本在 `@echo-agent/tools`)。工具目录不进 system。
26
26
 
27
27
  import { DEFAULT_MAX_ITERATIONS, type AssembleContext } from "@echo-agent/core"; // 执行预算的唯一出处(identity 读它)
28
28
  import { definePromptPack, type ExtensionEntry } from "@echo-agent/core/extension";
29
- import type { CredentialStore, PermissionPolicy as CorePermissionPolicy, PromptSection, Skill } from "@echo-agent/core";
30
- import { makeBashTool, makeShellTools } from "./tools/bash.ts";
31
- import { makeFsTools } from "./tools/fs.ts";
32
- import { makeSearchTools } from "./tools/search.ts";
33
- import { makeWebTools } from "./tools/web.ts";
29
+ import type { CredentialStore, PermissionPolicy, PermissionRules, PromptSection, Skill, ThinkingLevel } from "@echo-agent/core";
30
+ // 文件 / 搜索 / shell / web 四组工具、它们的 Extension 与习惯段不是本产品的,来自 `@echo-agent/tools`;本产品只决定挂不挂、沙箱开不开
31
+ import {
32
+ detectShellEnvironment,
33
+ makeFsTools,
34
+ makeSearchTools,
35
+ makeShellTools,
36
+ makeWebTools,
37
+ shellToolsSection,
38
+ toolsEntries,
39
+ workspaceToolsSection,
40
+ } from "@echo-agent/tools";
34
41
  import { makeWorktreeTools } from "./tools/worktree.ts";
35
- import { ECHO_SHELL, ECHO_WEB, ECHO_WORKSPACE, ECHO_WORKTREE } from "./extensions.ts";
36
- import { permissionPolicyFor, type PermissionPolicy } from "./permission.ts";
37
- import { codingConductSection, codingIdentitySection, shellToolsSection, workspaceToolsSection } from "./prompt.ts";
42
+ import { ECHO_WORKTREE } from "./extensions.ts";
43
+ import { permissionPolicyFor } from "./permission.ts";
44
+ import { codingConductSection, codingIdentitySection } from "./prompt.ts";
38
45
 
39
46
  export type CodingPresetOptions = {
40
- /** 权限策略;false = 全放行(评测/CI)。缺省「读随便,动手先问」——没配裁决人时动手会被拒。 */
41
- permission?: PermissionPolicy | false;
47
+ /**
48
+ * 权限规则表(内核的 `PermissionRules`);false = 不装策略、全放行(出厂 echo-coding 的管道形态就是这一档,见 `cli.ts`)。
49
+ * 不给 = `DEFAULT_PERMISSION`(`permission.ts`:bash / write_file / edit_file 先问)——没配裁决人时这三件会被拒。
50
+ */
51
+ permission?: PermissionRules | false;
42
52
  /**
43
53
  * 已经扫好的 skill。**本函数不扫盘**——它是同步的一份配置,读盘是调用方的事
44
54
  * (`loadSkills()` 在 core 公共面上)。评测传空就是「不加载仓库 skill」。
45
55
  */
46
56
  skills?: Skill[];
47
57
  maxIterations?: number;
58
+ /** 思考档位。缺省 {@link CODING_DEFAULT_THINKING};给了就用给的(`"off"` 照样是关)。 */
59
+ thinkingLevel?: ThinkingLevel;
48
60
  /**
49
61
  * 凭据来源:`web_search` 从这里读搜索服务的 key(`brave`),排在环境变量 `BRAVE_API_KEY` 之后。
50
62
  * 不给 = 只认环境变量(评测、低层装配)。宿主给的是与模型 key 同一个 store(`PresetForm.credentials`)。
51
63
  */
52
64
  credentials?: CredentialStore;
65
+ /**
66
+ * bash 的命令包进操作系统沙箱跑(2026-11-15,`@echo-agent/tools` 的 `sandbox.ts`):只能写工作区、临时目录与包管理器缓存,读不到 echo 的凭据文件。
67
+ * 缺省不开。开了之后模型能带 `sandbox: false` 让某一条在沙箱外跑——那一条要有人把关(内核的安全分类器,或权限策略问人),
68
+ * 只开沙箱、不装权限策略的话这扇门没人看。
69
+ */
70
+ sandbox?: boolean;
53
71
  };
54
72
 
55
73
  /**
@@ -60,11 +78,12 @@ export type CodingPresetOptions = {
60
78
  */
61
79
  export type CodingPreset = {
62
80
  agent: {
63
- permission?: CorePermissionPolicy;
81
+ permission?: PermissionPolicy;
64
82
  // `Skill[]` 而不是 `readonly Skill[]`:形状跟着 `AgentOptions` 走,
65
83
  // 自己另定一份「更严格」的类型只会在 spread 进 `createEcho()` 时打架。
66
84
  skills?: Skill[];
67
85
  maxIterations?: number;
86
+ thinkingLevel?: ThinkingLevel;
68
87
  };
69
88
  extensions: readonly ExtensionEntry[];
70
89
  };
@@ -72,6 +91,13 @@ export type CodingPreset = {
72
91
  /** 缺省模型的**唯一**出处:identity 与调用方都读它,不各手抄一份(review 五轮 #3)。 */
73
92
  export const CODING_DEFAULT_MODEL = { provider: "kimi", model: "kimi-k3" } as const;
74
93
 
94
+ /**
95
+ * 缺省思考档(2026-11-03 拍板,`docs/decisions/implemented/2026-11-03-coding-default-thinking-medium.md`):
96
+ * core 新建 agent 缺省 `"off"`,能真关思考的模型(DeepSeek、Kimi K2.6)一起来就不思考,管道形态又没有档位可切。
97
+ * coding 要多步推理,缺省开 medium(codex 的缺省 reasoning effort 也是 medium);各家怎么映射见模型目录的 `thinkingLevelMap`。
98
+ */
99
+ const CODING_DEFAULT_THINKING: ThinkingLevel = "medium";
100
+
75
101
  /** 产品的身份 + 编码纪律,一条 prompt pack。 */
76
102
  const ECHO_CODING_PROMPT = definePromptPack("echo:coding");
77
103
 
@@ -110,9 +136,15 @@ const AGENT_BUILTIN_TOOLS = [
110
136
  // 「这个产品自己带什么」——把容器的选择写进产品身份,换个宿主就对不上了。
111
137
  ] as const;
112
138
 
113
- /** 产品自己出的四段(identity / conduct:coding / tool:workspace / tool:shell),按 order 排。 */
139
+ /**
140
+ * 产品自己出的四段(identity / conduct:coding / tool:workspace / tool:shell),按 order 排。
141
+ * `tool:shell` 末尾那句运行环境与 `echo:shell` 装配时取的是同一个来源(`detectShellEnvironment`),
142
+ * 所以 digest 随机器的平台与 bash 版本变——同一台机器上两次调用仍相等。
143
+ */
114
144
  function productSections(): PromptSection[] {
115
- return [codingIdentitySection(), codingConductSection(), workspaceToolsSection(), shellToolsSection()].sort((a, b) => a.order - b.order);
145
+ return [codingIdentitySection(), codingConductSection(), workspaceToolsSection(), shellToolsSection(detectShellEnvironment())].sort(
146
+ (a, b) => a.order - b.order,
147
+ );
116
148
  }
117
149
 
118
150
  /** digest 用的固定装配上下文:产品四段都不引用变量,所以值无关紧要,只求确定。 */
@@ -154,32 +186,23 @@ export function codingAgentIdentity(): {
154
186
  }
155
187
 
156
188
  export function codingPreset(opts: CodingPresetOptions = {}): CodingPreset {
189
+ // 工具包的三条(`echo:workspace` / `echo:shell` / `echo:web`):条目怎么造归工具包,本产品只说沙箱开不开、凭据从哪来
190
+ const [workspace, shell, web] = toolsEntries({ sandbox: opts.sandbox, credentials: opts.credentials }) as [ExtensionEntry, ExtensionEntry, ExtensionEntry];
157
191
  return {
158
192
  agent: {
159
193
  ...(opts.permission !== false ? { permission: permissionPolicyFor(opts.permission) } : {}),
160
194
  ...(opts.skills !== undefined && opts.skills.length > 0 ? { skills: opts.skills } : {}),
161
195
  ...(opts.maxIterations !== undefined ? { maxIterations: opts.maxIterations } : {}),
196
+ thinkingLevel: opts.thinkingLevel ?? CODING_DEFAULT_THINKING,
162
197
  },
163
198
  extensions: [
164
199
  // 产品的身份与编码纪律
165
200
  { entryId: "echo:coding", definition: ECHO_CODING_PROMPT, config: { sections: [codingIdentitySection(), codingConductSection()] } },
166
- // fs / search 的工具是纯函数造出来的,可以在装配前就备好 → 走 `defineToolPack` 的 config;
167
- // 它们的跨调用习惯段跟工具同一个 config 进来:工具卸了段也走
168
- {
169
- entryId: "echo:workspace",
170
- definition: ECHO_WORKSPACE,
171
- config: { tools: [...makeFsTools(), ...makeSearchTools()], sections: [workspaceToolsSection()] },
172
- },
173
- // bash 不行:它要 `agent.background`。所以 `echo:shell` 自己 inject 那条能力端口并在 apply 里
174
- // 注册工具与段,这里只列 definition、不给 config(见 `extensions.ts` 的注释)。
175
- { entryId: "echo:shell", definition: ECHO_SHELL },
176
- // worktree 隔离要 `AgentRuntime.setWorkspace`,同 shell 一样自己 inject(2026-09-03)
201
+ workspace,
202
+ shell,
203
+ // worktree 隔离是本产品自己的:要 `AgentRuntime.setWorkspace`,自己 inject(2026-09-03)。夹在 shell 与 web 之间是原来的挂载顺序,不动它
177
204
  { entryId: "echo:worktree", definition: ECHO_WORKTREE },
178
- // 取网页 / 搜索:纯函数工具,config 进来;延迟工具,经 tool_search 取过才上菜单
179
- { entryId: "echo:web", definition: ECHO_WEB, config: { tools: makeWebTools({ credentials: opts.credentials }) } },
205
+ web,
180
206
  ],
181
207
  };
182
208
  }
183
-
184
- /** `bash` 单独造一把(不经 Extension)。`makeShellTools()` 与测试都从这里造。 */
185
- export { makeBashTool };
package/src/cli.ts CHANGED
@@ -7,16 +7,22 @@
7
7
  // 装配、收摊全在 base 的 `mainFor()` 里,这里一行都不复制;交互形态起哪个壳由本文件挑
8
8
  // (`terminalShell`),装配层不写死。
9
9
  //
10
- // **权限:缺省全放行**(2026-09-01 用户拍板,两种形态都是)。`permission: false` = 不装策略,
11
- // bash / write_file / edit_file 不问直接跑。理由:这是用户自己在自己的仓库里开的 coding agent,
12
- // 每一步都问只会让人按到麻木;管道形态更是没人可问。要「动手先问」的策略仍在
13
- // `permission.ts`(`DEFAULT_PERMISSION` + `responder: "host"`,壳会摆出来问 y/n),
14
- // 评测或别的宿主可以自己传——本产品不缺省开它。
10
+ // **权限**:2026-09-01 定的是两种形态都全放行——每一步都问只会让人按到麻木,管道形态更是没人可问。
11
+ // 2026-11-15 起两层兜底,都不是本产品自己的机制:
12
+ // · **安全分类器**是内核的(`createEcho({ safetyClassifier })`),开不开归使用者(settings.json 的 `safetyClassifier`,
13
+ // 不写按形态:交互开、管道关——装配层 `presetForm` 定)。本产品只交**形状**:哪些工具不用判(`CODING_SAFE_TOOLS`:
14
+ // 工具包那份加上本产品的 worktree 两件)、bash 的 `sandbox: false` 是什么意思(工具包的 `SHELL_CLASSIFIER_NOTES`)。
15
+ // · **交互形态命令包进操作系统沙箱**(只能写工作区、临时目录与缓存,`@echo-agent/tools` 的 `sandbox.ts`)。分类器关着时,越出沙箱的那一条
16
+ // 由人看(`permissionPolicyFor` 的规矩);开着时由分类器判,不另装策略。
17
+ // `permission.ts` 的 `DEFAULT_PERMISSION`(三件先问的黑名单)**不是这条命令的行为**:它只在嵌入方调 `codingPreset()`
18
+ // 而不传 `permission` 时生效(评测、别的宿主)。
15
19
 
16
20
  import { readFileSync } from "node:fs";
17
21
  import { conductEntry, mainFor, retainRecentDays, type Product } from "@echo-agent/base";
18
22
  import { terminalShell } from "@echo-agent/tui";
19
23
  import { codingPreset } from "./agent.ts";
24
+ import { SHELL_CLASSIFIER_NOTES } from "@echo-agent/tools";
25
+ import { CODING_SAFE_TOOLS } from "./permission.ts";
20
26
 
21
27
  /** 本包的版本,欢迎头里显示。`../package.json` 在源码树和 tarball 里都在这个相对位置。 */
22
28
  const VERSION: string = (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string })
@@ -35,8 +41,14 @@ export const ECHO_CODING: Product = Object.freeze({
35
41
  // 共用的纪律段由**产品**挂(2026-09-09 拍板):装配层不再恒挂,形态决定「有没有人能答」那一条。
36
42
  // `codingPreset()` 自己只依赖 core,所以这一条加在这里,不加进它。
37
43
  preset: (form, host) => {
38
- const preset = codingPreset({ permission: false, maxIterations: 200, credentials: host.credentials });
39
- return { ...preset, extensions: [conductEntry(form), ...preset.extensions] };
44
+ // 沙箱跟形态走:交互形态包、管道形态不包。分类器关着时越出沙箱的那一条问终端里的人;开着时交给分类器(见文件头)
45
+ const permission = form.interactive && !form.safetyClassifier ? ({ fallback: "allow", responder: "host" } as const) : false;
46
+ const preset = codingPreset({ permission, sandbox: form.interactive, maxIterations: 200, credentials: host.credentials });
47
+ return {
48
+ ...preset,
49
+ extensions: [conductEntry(form), ...preset.extensions],
50
+ safetyClassifier: { safeTools: CODING_SAFE_TOOLS, notes: SHELL_CLASSIFIER_NOTES },
51
+ };
40
52
  },
41
53
  // 观测留 30 天(2026-09-15 用户拍板,与 echo-agent 同一条规则;两个产品平级,各自声明各自的)。
42
54
  observationExpiry: retainRecentDays(30),
package/src/extensions.ts CHANGED
@@ -1,30 +1,17 @@
1
- // coding agent 自己那几件工具的 Extension 形态:`echo:workspace` 与 `echo:shell`。
1
+ // coding agent 自己那一条工具 Extension:`echo:worktree`(git worktree 是编码才有的事)。
2
+ // 文件 / 搜索 / shell / web 那三条(`echo:workspace` / `echo:shell` / `echo:web`)不属于本产品,在 `@echo-agent/tools`,
3
+ // 本产品在 `codingPreset()` 里挂它们。
2
4
  //
3
5
  // **为什么不是直接 `registerTool()`**(2026-08-31 用户拍板:「机制必须同一份,都要走 extension」):
4
6
  // 直调那条路没有 owner——装上去的工具没人持 disposer,卸不掉、也不出现在能力清单里。
5
- // 走 Extension 之后,产品层的工具与内建、与第三方**同一个 `AgentTools.register`、同一份所有权账本**,
6
- // 并且规格明写 first-party Extension「是公开扩展面是否够用的第一个 conformance consumer」——
7
- // 我们自己先用一遍,扩展作者才不会撞上只有他们能看见的坑。
8
- //
9
- // **`defineToolPack` 与 `registerAll` 都来自 `@echo-agent/core/extension`,不在这里另抄一份**(review 二轮 P1;
10
- // 2026-09-14 `registerAll` 导出后,下面两条扩展手抄的逆序撤销也换成了它):
11
- // 上一版这里复制了 core 的实现,于是「注册中途撞名要整组回滚」那个修复得改两处——
12
- // 复制一份实现就是复制一份将来会漏修的地方。
7
+ // 走 Extension 之后,产品层的工具与内建、与第三方**同一个 `AgentTools.register`、同一份所有权账本**。
13
8
 
14
- import { AgentBackgroundService, AgentPrompt, AgentRuntimeService, AgentTools, defineExtension, defineToolPack, registerAll } from "@echo-agent/core/extension";
15
- import { makeShellTools } from "./tools/bash.ts";
9
+ import { AgentRuntimeService, AgentTools, defineExtension, registerAll } from "@echo-agent/core/extension";
16
10
  import { makeWorktreeTools } from "./tools/worktree.ts";
17
- import { shellToolsSection } from "./prompt.ts";
18
-
19
- /** 工作区读写与搜索:`read_file` / `write_file` / `edit_file` / `glob` / `grep` / `list_dir`。 */
20
- export const ECHO_WORKSPACE = defineToolPack("echo:workspace");
21
-
22
- /** 取网页与搜索:`web_fetch` / `web_search`(延迟工具)。纯函数造的工具,config 进来即可。 */
23
- export const ECHO_WEB = defineToolPack("echo:web");
24
11
 
25
12
  /**
26
13
  * worktree 隔离:`worktree_enter` / `worktree_exit`(2026-09-03 用户拍板 B)。
27
- * 与 `echo:shell` 同一个理由不用 `defineToolPack`:工具要 `AgentRuntime.setWorkspace`,那是 Agent 上的东西,
14
+ * 不用 `defineToolPack`:工具要 `AgentRuntime.setWorkspace`,那是 Agent 上的东西,
28
15
  * 装配前拿不到——从 `AgentRuntimeService` 注入(`echo:agent` 恒 provide,排在所有扩展之前)。
29
16
  */
30
17
  export const ECHO_WORKTREE = defineExtension({
@@ -44,47 +31,3 @@ export const ECHO_WORKTREE = defineExtension({
44
31
  });
45
32
  },
46
33
  });
47
-
48
- /**
49
- * 受权限管控的命令执行:`bash`。
50
- *
51
- * **它不用 `defineToolPack`,因为工具造不出来**:bash 要 `agent.background` 才支持
52
- * `background: true`,而那是 Agent 实例上的东西——装配层在调 `createEcho()` 之前拿不到它。
53
- * 上一版的做法是产品层自己 `new Agent()` 再自己 mount,也就是**第二个装配现场**。
54
- *
55
- * 现在换成从 `ctx` 拿:core 2026-08-31 把后台队列做成能力端口
56
- * (`AgentBackgroundService`,见 `extension/registries.ts` 文件头)。于是本扩展变成
57
- * 纯静态的一条 definition,装配层只管把它列进 `createEcho({ extensions })`。
58
- *
59
- * **`required: true`,不是软依赖**(2026-08-31 review 三轮 P1 修正):上一版写的是 `required: false`,
60
- * 理由是「没接后台队列照样能跑命令」——但 apply 里无条件 `ctx.get()`,缺 provider 一样抛,review 实测整代装不上
61
- * (那时 ABI 也没有不抛的读法;2026-09-14 加了 `ctx.tryGet()`,软依赖从此有正式用法,但那是给真会缺席的
62
- * Service 用的)。`agent.background` 是 **Agent 恒有的能力**(构造函数无条件造),任何由 Agent 造出来的 registries
63
- * 都提供得了它,所以这里就该是硬依赖:走 `createEcho()` 恒有;自己搭 Host 而不传 `background` 就在 PREPARE 装不上,
64
- * 报错明确指向缺的那条 Service——比装上一个「bash 在但后台不灵」的半残工具好。
65
- *
66
- * (`makeBashTool()` 的 `deps.background` 仍是可选:单独造工具、不接后台队列时 `background: true` 不可用,
67
- * 与本扩展的装配前提是两件事。)
68
- */
69
- export const ECHO_SHELL = defineExtension({
70
- name: "echo:shell",
71
- hostAbiVersion: 1,
72
- inject: {
73
- tools: { service: AgentTools, required: true },
74
- background: { service: AgentBackgroundService, required: true },
75
- prompt: { service: AgentPrompt, required: true },
76
- },
77
- apply(ctx) {
78
- const registry = ctx.get(AgentTools);
79
- const prompt = ctx.get(AgentPrompt);
80
- // bash + job_output / job_stop:同一张后台任务表(`agent.background`),一起装、一起撤
81
- const tools = makeShellTools({ background: ctx.get(AgentBackgroundService) });
82
- void ctx.effect({
83
- // 与 `defineToolPack` 同一档:工具面每轮都可能变,声明得比实际需要强会挡住热重载
84
- boundary: "turn",
85
- // 工具与它们的习惯段(`tool:shell`)同一个 effect:一起装、一起撤。
86
- // 中途撞名要把已注册的撤回去——半组工具在、半组不在,比整组不在更难排查(`registerAll`,与内建同一份)
87
- start: () => registerAll([...tools.map((tool) => () => registry.register(tool)), () => prompt.section(shellToolsSection())]),
88
- });
89
- },
90
- });
package/src/index.ts CHANGED
@@ -3,15 +3,13 @@
3
3
  // **装配仍归 `createEcho()`,启动器部件归 `@echo-agent/base`**:`codingPreset()` 出配置;可执行文件
4
4
  // `echo-coding` 是 base 的 `mainFor()` 绑上本产品与一个壳(`cli.ts`)。原先的 `createCodingAgent()`
5
5
  // 自己造 Agent、造 Host、mount、收摊——那是第二个 composition root,2026-08-31 删掉了。
6
+ //
7
+ // 文件 / 搜索 / shell / web 四组工具不在这里:它们不是 coding 独有的,在 `@echo-agent/tools`,
8
+ // 本产品只在 `codingPreset()` 里挂上。要单独用这些工具的从那个包拿。
6
9
 
7
10
  /** 可执行文件的实质:装配层的启动逻辑绑上本产品。`bin/echo-coding.ts` 调的就是它。 */
8
11
  export { main, ECHO_CODING } from "./cli.ts";
9
12
  export { codingPreset, CODING_DEFAULT_MODEL } from "./agent.ts";
10
13
  export type { CodingPreset, CodingPresetOptions } from "./agent.ts";
11
- export { ECHO_SHELL, ECHO_WORKSPACE } from "./extensions.ts";
12
- export { makeFsTools, resolveSafe } from "./tools/fs.ts";
13
- export { makeBashTool, makeShellTools } from "./tools/bash.ts";
14
- export type { BashDeps } from "./tools/bash.ts";
15
- export { makeSearchTools } from "./tools/search.ts";
14
+ // 规则表的类型(`PermissionRules` / `PermissionRule`)与换成策略的函数是内核的,从 `@echo-agent/core` 拿;这里只有本产品的内容
16
15
  export { permissionPolicyFor, DEFAULT_PERMISSION } from "./permission.ts";
17
- export type { PermissionPolicy, PermissionRule } from "./permission.ts";
package/src/permission.ts CHANGED
@@ -1,64 +1,46 @@
1
- // 权限:产品策略翻译成 core 的 authorization stage,不再是一条 preToolUse hook。
1
+ // 权限:echo-coding 这一头只剩**内容**——缺省规则表里点哪几件工具、交给安全分类器的名单里补哪几件。
2
2
  //
3
- // 三档规则不变:allow(放行)/ deny(拒)/ ask(问裁决人)。规则在构造期交给 Agent
4
- // (`permissionPolicyFor()` → `EchoAgentOptions.permission`),跑在固定 stage:
5
- // transform hooks → 重新校验 → freeze → authorization → execute。裁决看到的是冻结后的最终参数,
6
- // 人批准的和工具执行的是同一份;hook 在它之后改不了参数。
7
- //
8
- // **裁决人不在这一层**(2026-08-31):原先本文件还有个 `installPermission()`,
9
- // 订阅 `permissionRequest` 去问一个回调、再 `answerPermission()`。那件事现在归**壳**——
10
- // `echo-agent` 的 `echo:tui` 已经在做(摆问题、收 y/n、答复、处理 `permissionCancelled`),
11
- // 而仓库里从来没有调用方给过那个回调。两份实现只有一份被行使,删掉没被行使的那份。
12
- // 于是本文件只剩「规则怎么判」,`responder` 只声明**有没有人会答**,不自己找人答。
3
+ // 机制都不在这里(2026-11-15):
4
+ // · 规则表怎么判(allow / deny / ask、表里没有的走 fallback、有没有人答)是内核的:`@echo-agent/core` 的
5
+ // `PermissionRules` 与 `permissionPolicyFromRules()`;
6
+ // · 「越出沙箱从不悄悄放行」跟着 bash 走:`@echo-agent/tools` 的 `askOutsideSandbox()`;
7
+ // · 安全分类器是内核的(`createEcho({ safetyClassifier })`),文件 / shell / web 工具的免判名单与 bash 的说明
8
+ // 跟着工具走(`TOOLS_SAFE_TOOLS` / `SHELL_CLASSIFIER_NOTES`)。
13
9
  //
14
- // **没有裁决人时 ask 视为 deny**——诚实缺席:宁可拦下,不可因为没人问就默默放行。
15
- // 这条由 `responder:"none"` 表达:core 在 authorize 阶段就把 ask 折成 policy deny,不生成 ask、不等人。
16
-
17
- import type { PermissionPolicy as CorePermissionPolicy } from "@echo-agent/core";
18
-
19
- export type PermissionRule = "allow" | "deny" | "ask";
10
+ // 规则在构造期交给 Agent(`permissionPolicyFor()` → `createEcho({ agent: { permission } })`),跑在固定 stage:
11
+ // transform hooks → 重新校验 → freeze → authorization → execute。裁决看到的是冻结后的最终参数,
12
+ // 人批准的和工具执行的是同一份;hook 在它之后改不了参数。裁决人归壳(终端里摆问题、收 y/n),不在这一层。
20
13
 
21
- export type PermissionPolicy = {
22
- /** 按工具名给规则。 */
23
- rules?: Record<string, PermissionRule>;
24
- /** 表里没有的工具走这档,缺省 "allow"。 */
25
- fallback?: PermissionRule;
26
- /**
27
- * ask 有没有人答。
28
- *
29
- * - `"host"`:宿主会答(交互式壳:`echo-agent` 在终端里摆出来问 y/n)。
30
- * - `"none"`(缺省):**没人答,ask 直接折成 deny**。管道形态、CI 与评测都是这一档。
31
- *
32
- * 缺省选 `none` 是因为**猜错的代价不对称**:以为有人答而其实没有 → 工具永远挂着等;
33
- * 以为没人答而其实有 → 用户看到一次多余的拒绝,重跑即可。
34
- */
35
- responder?: "host" | "none";
36
- };
14
+ import { permissionPolicyFromRules, type PermissionPolicy, type PermissionRules } from "@echo-agent/core";
15
+ import { TOOLS_SAFE_TOOLS, askOutsideSandbox } from "@echo-agent/tools";
37
16
 
38
17
  /**
39
- * 缺省策略:读随便;**bash / write_file / edit_file 先问**,其余放行——与 Claude Code 的缺省一个精神。
18
+ * `codingPreset()` 的缺省规则表:读随便;**bash / write_file / edit_file 先问**,其余放行——与 Claude Code 的缺省一个精神。
19
+ *
20
+ * **适用范围**:只在嵌入方调 `codingPreset()` 而不传 `permission` 时生效(评测、别的宿主)。出厂的 `echo-coding`
21
+ * 命令不用它(理由写在 `cli.ts` 文件头)。
22
+ *
40
23
  * 这是一张黑名单而不是白名单(2026-09-09 拍板,`docs/decisions/implemented/2026-09-09-default-permission-blacklist.md`):
41
24
  * 「其余」里也有动东西的,各有各的不问的理由——worktree_enter 开的是新分支与新目录,可逆;worktree_exit 的删除
42
25
  * 由 git 自己挡(有未提交改动就拒,分支保留);web_fetch / web_search 出网不问(2026-09-03 拍板);core 内建的
43
26
  * 记忆 / 任务 / 技能 / 闹钟写的是 agent 自己的状态,不是用户的世界。要更严的产品自己给 `rules`。
44
27
  * bash 不受工作区边界约束,它靠的正是这一条 ask。
45
28
  */
46
- export const DEFAULT_PERMISSION: PermissionPolicy = {
29
+ export const DEFAULT_PERMISSION: PermissionRules = {
47
30
  rules: { bash: "ask", write_file: "ask", edit_file: "ask" },
48
31
  fallback: "allow",
49
32
  };
50
33
 
51
- /** 把产品策略翻译成 core 的 stage 策略——构造期经 `createEcho({ agent: { permission } })` 交给 core。 */
52
- export function permissionPolicyFor(policy: PermissionPolicy = DEFAULT_PERMISSION): CorePermissionPolicy {
53
- return {
54
- authorize: ({ toolName }) => {
55
- const rule = policy.rules?.[toolName] ?? policy.fallback ?? "allow";
56
- if (rule === "allow") return { kind: "allow" };
57
- if (rule === "deny") return { kind: "deny", reason: `Tool '${toolName}' was denied by the permission policy` };
58
- return { kind: "ask", reason: `Tool '${toolName}' was not authorized: it needs approval from a responder` };
59
- },
60
- // 交互 CLI 等人不超时;没有裁决人就是 none——core 会把 ask 折成 deny
61
- askTimeoutMs: null,
62
- responder: policy.responder ?? "none",
63
- };
34
+ /**
35
+ * echo-coding 交给安全分类器的免判名单(`SafetyClassifierOptions.safeTools`):工具包那份,加上本产品自己的两件——
36
+ * worktree(新分支新目录,可逆)。内核自己的工具由内核的名单管。
37
+ */
38
+ export const CODING_SAFE_TOOLS: readonly string[] = Object.freeze([...TOOLS_SAFE_TOOLS, "worktree_enter", "worktree_exit"]);
39
+
40
+ /**
41
+ * 规则表 → Agent 收的策略,外加「越出沙箱从不悄悄放行」:bash 带 `sandbox: false` 时,规则是 `allow` 也改成 `ask`。
42
+ * 安全分类器开着时出厂产品不装这份策略(越界那一条由分类器判,`cli.ts`);关着时就靠它让人看一眼。
43
+ */
44
+ export function permissionPolicyFor(table: PermissionRules = DEFAULT_PERMISSION): PermissionPolicy {
45
+ return askOutsideSandbox(permissionPolicyFromRules(table));
64
46
  }
package/src/prompt.ts CHANGED
@@ -1,11 +1,7 @@
1
1
  // echo-coding 自己拥有的 prompt 段(2026-09-01 拍定,决策见 memory `prompt-design-decisions-2026-09-01`):
2
2
  // · identity(order 0)与 conduct:coding(order 11)——产品身份与编码纪律,**不点工具名**
3
- // · tool:workspace(order 100)、tool:shell(order 101)——文件与 shell 工具的**跨调用习惯**,
4
- // 由拥有这些工具的 extension(`echo:workspace` / `echo:shell`)注册:工具在段在,工具卸段走
5
- // 单工具的语义(参数、上限)只在各工具的 description;这里只写 description 装不下的「几个工具怎么选」。
3
+ // 文件与 shell 工具的跨调用习惯段(tool:workspace / tool:shell)跟着工具走,在 `@echo-agent/tools`。
6
4
  // 文本是模型逐字读的资产,全英文;改动这里 = 改被测行为(`codingAgentIdentity()` 的 digest 会变)。
7
- // `tool:shell` 里的 120 s、`background: true`、非零退出码走 error,都是 `tools/bash.ts` 的**真实行为**——
8
- // 行为变了这段跟着改,不许两边说的不一样。
9
5
 
10
6
  import { PROMPT_ORDER, type PromptSection } from "@echo-agent/core";
11
7
 
@@ -18,14 +14,9 @@ export const CODING_CONDUCT = `# Working in code
18
14
  - Change only what the task requires. No drive-by refactors, no speculative abstractions, no compatibility shims for code you can simply change.
19
15
  - A change is done when you have run the checks that prove it: the tests, the type check, or the command the user relies on. If you could not run them, say so.
20
16
  - Do not commit, push, or publish unless the user asks.
17
+ - Uncommitted changes may be the user's own work in progress. Run \`git status\` before any git command that rewrites the working tree or history, and never throw away changes you did not make: no \`git reset --hard\`, \`git checkout -- .\`, \`git restore .\`, \`git clean -f\`, \`git stash drop\` or \`git push --force\` unless the user asks for exactly that.
21
18
  - Add a comment only for a constraint the code cannot show; do not restate the code.`;
22
19
 
23
- export const WORKSPACE_TOOLS = `# Files
24
- The six file tools (read_file, write_file, edit_file, list_dir, glob, grep) are confined to the workspace: relative paths resolve from its root, and a path that leads outside it, directly or through a symlink, is refused. bash is not confined. See a directory's entries with list_dir, find files with glob, and search contents with grep (a directory or a single file) rather than running ls, find or rg through bash. edit_file and write_file refuse a file you have not read with read_file in this session, or that changed on disk since you read it: read it (again) first. Change an existing file with edit_file (exact, unique match; replace_all for a rename); use write_file only to create a file or rewrite it entirely.`;
25
-
26
- export const SHELL_TOOLS = `# Shell
27
- The working directory carries over between bash calls (it starts at the workspace root and cd persists; the reply tells you when it changed); shell variables and functions do not, so set them in the same call that uses them. Commands time out after 120 s by default; for long-running processes (servers, watchers) pass background: true and keep working — read the job's output with job_output, stop it with job_stop, and you are notified when it ends. A non-zero exit code comes back as an error with the output; read it before deciding the command worked. Today's date is not in your context; run \`date\` when it matters.`;
28
-
29
20
  export function codingIdentitySection(): PromptSection {
30
21
  return { name: "identity", order: PROMPT_ORDER.identity, render: () => CODING_IDENTITY };
31
22
  }
@@ -33,11 +24,3 @@ export function codingIdentitySection(): PromptSection {
33
24
  export function codingConductSection(): PromptSection {
34
25
  return { name: "conduct:coding", order: PROMPT_ORDER.conduct + 1, render: () => CODING_CONDUCT };
35
26
  }
36
-
37
- export function workspaceToolsSection(): PromptSection {
38
- return { name: "tool:workspace", order: PROMPT_ORDER.tools, render: () => WORKSPACE_TOOLS };
39
- }
40
-
41
- export function shellToolsSection(): PromptSection {
42
- return { name: "tool:shell", order: PROMPT_ORDER.tools + 1, render: () => SHELL_TOOLS };
43
- }