@echo-agent/coding 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 echo-yiyi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,44 @@
1
+ # @echo-agent/coding
2
+
3
+ Echo's coding agent: file, search, shell and web tools mounted on top of
4
+ [`echo-agent`](https://www.npmjs.com/package/echo-agent). Installs the `echo-coding` command.
5
+
6
+ > **Requires [Bun](https://bun.sh/).** The executable is TypeScript with a `#!/usr/bin/env bun`
7
+ > shebang, and the package entry point is TypeScript source. Node is not supported for this
8
+ > package.
9
+
10
+ > **Status: pre-release.** Nothing is published to npm yet and the public surface may change
11
+ > before the first `0.x` release. Install from source for now.
12
+
13
+ ## Run it
14
+
15
+ ```bash
16
+ git clone https://github.com/echo-yiyi/echo-agent.git
17
+ cd echo-agent
18
+ bun install
19
+ MOONSHOT_API_KEY=sk-... bun packages/coding/bin/echo-coding.ts
20
+ ```
21
+
22
+ The command name stays `echo-coding` even though the package is scoped — the unscoped name was
23
+ already taken on npm by an unrelated project.
24
+
25
+ `echo-coding` accepts the same options as `echo-agent` (`--help`). **It runs every tool without
26
+ asking**, in the interactive UI and through a pipe alike — treat it as a script that may change
27
+ files in the current directory.
28
+
29
+ Sessions belong to a directory *and* a command, so `echo-agent` and `echo-coding` never share a
30
+ conversation even in the same directory.
31
+
32
+ ## What this package is
33
+
34
+ A **product**, not a framework layer. It owns its system prompt, its permission policy and the
35
+ `echo:workspace`, `echo:shell`, `echo:worktree` and `echo:web` extensions, then hands that preset
36
+ to `echo-agent`'s startup logic. It does not change a line of `echo-agent` — which is exactly the
37
+ path a third-party product would take on this runtime.
38
+
39
+ Full documentation is in the
40
+ [repository README](https://github.com/echo-yiyi/echo-agent#readme).
41
+
42
+ ## License
43
+
44
+ MIT. See [LICENSE](https://github.com/echo-yiyi/echo-agent/blob/main/LICENSE).
@@ -0,0 +1,9 @@
1
+ #!/usr/bin/env bun
2
+ // `echo-coding` —— coding agent 产品的**唯一**可执行入口。形状照 `echo-agent` 的 `bin/echo-agent.ts`。
3
+ //
4
+ // **这里只做一件事**:把 argv 交给 `main()`,把它的返回值当退出码。
5
+ // 逻辑一行都不放这儿——放了就只能靠 spawn 才测得到。
6
+
7
+ import { main } from "../src/cli.ts";
8
+
9
+ process.exitCode = await main(process.argv.slice(2));
package/package.json ADDED
@@ -0,0 +1,50 @@
1
+ {
2
+ "name": "@echo-agent/coding",
3
+ "version": "0.1.0",
4
+ "license": "MIT",
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.",
7
+ "bin": {
8
+ "echo-coding": "./bin/echo-coding.ts"
9
+ },
10
+ "dependencies": {
11
+ "@echo-agent/base": "0.1.0",
12
+ "@echo-agent/core": "0.1.0",
13
+ "@echo-agent/tui": "0.1.0"
14
+ },
15
+ "devDependencies": {
16
+ "@types/bun": "latest",
17
+ "typescript": "^5.5.0"
18
+ },
19
+ "exports": {
20
+ ".": "./src/index.ts"
21
+ },
22
+ "scripts": {
23
+ "typecheck": "tsc --noEmit",
24
+ "test": "bun test test"
25
+ },
26
+ "files": [
27
+ "src",
28
+ "bin",
29
+ "LICENSE",
30
+ "README.md"
31
+ ],
32
+ "keywords": [
33
+ "agent",
34
+ "ai-agent",
35
+ "llm",
36
+ "coding-agent",
37
+ "cli",
38
+ "bun"
39
+ ],
40
+ "repository": {
41
+ "type": "git",
42
+ "url": "git+https://github.com/echo-yiyi/echo-agent.git",
43
+ "directory": "packages/coding"
44
+ },
45
+ "homepage": "https://github.com/echo-yiyi/echo-agent#readme",
46
+ "bugs": "https://github.com/echo-yiyi/echo-agent/issues",
47
+ "engines": {
48
+ "bun": ">=1.3.0"
49
+ }
50
+ }
package/src/agent.ts ADDED
@@ -0,0 +1,183 @@
1
+ // `codingPreset()`:**一份配置,不是一个装配现场**(2026-08-31 用户拍板)。
2
+ //
3
+ // ## 它替掉了什么
4
+ //
5
+ // 原先这里是 `createCodingAgent()`:自己造 Models、自己 `new Agent()`、自己造 ExtensionHost、
6
+ // 自己 mount 两代、自己 `loadTasks`、自己实现一套与 `Echo.stop()` 同形的收摊。
7
+ // 那就是**第二个 composition root**——而这一路刚立的规矩是「装配只有一处」。
8
+ // 更要命的是它会分家:`createEcho()` 后来补的每一条(inline 工具转 Extension、
9
+ // 清单与真相相等、失败路径逆序卸载),这边都得再补一遍,漏一条就是两种行为。
10
+ //
11
+ // 现在这里只出**数据**:权限策略、三条 Extension 的 Entry(产品的 prompt 段也在其中)。
12
+ // 装配归 `createEcho()`,一处。
13
+ //
14
+ // ```ts
15
+ // const echo = await createEcho({
16
+ // provider: kimiProvider(),
17
+ // workspace: root, // session 级事实,宿主给(2026-09-01)
18
+ // ...codingPreset(),
19
+ // });
20
+ // await echo.agent.start();
21
+ // ```
22
+ //
23
+ // system prompt(2026-09-01):不再有 `systemPrompt` 字符串。产品的身份与编码纪律是 `echo:coding`
24
+ // 这条 prompt pack 的两段;文件 / shell 工具的习惯段随 `echo:workspace` / `echo:shell` 走
25
+ // (文本都在 `prompt.ts`)。工具目录不进 system。
26
+
27
+ import { DEFAULT_MAX_ITERATIONS, type AssembleContext } from "@echo-agent/core"; // 执行预算的唯一出处(identity 读它)
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";
34
+ 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";
38
+
39
+ export type CodingPresetOptions = {
40
+ /** 权限策略;false = 全放行(评测/CI)。缺省「读随便,动手先问」——没配裁决人时动手会被拒。 */
41
+ permission?: PermissionPolicy | false;
42
+ /**
43
+ * 已经扫好的 skill。**本函数不扫盘**——它是同步的一份配置,读盘是调用方的事
44
+ * (`loadSkills()` 在 core 公共面上)。评测传空就是「不加载仓库 skill」。
45
+ */
46
+ skills?: Skill[];
47
+ maxIterations?: number;
48
+ /**
49
+ * 凭据来源:`web_search` 从这里读搜索服务的 key(`brave`),排在环境变量 `BRAVE_API_KEY` 之后。
50
+ * 不给 = 只认环境变量(评测、低层装配)。宿主给的是与模型 key 同一个 store(`PresetForm.credentials`)。
51
+ */
52
+ credentials?: CredentialStore;
53
+ };
54
+
55
+ /**
56
+ * 交给 `createEcho()` 的配置片段:`...codingPreset()` 展开即可。
57
+ *
58
+ * 形状对着 `CreateEchoOptions` 的两个字段,故意不多包一层——多一层就得跟着
59
+ * `createEcho` 的入参演进,而那正是上一版「两处各写一遍」的病根。
60
+ */
61
+ export type CodingPreset = {
62
+ agent: {
63
+ permission?: CorePermissionPolicy;
64
+ // `Skill[]` 而不是 `readonly Skill[]`:形状跟着 `AgentOptions` 走,
65
+ // 自己另定一份「更严格」的类型只会在 spread 进 `createEcho()` 时打架。
66
+ skills?: Skill[];
67
+ maxIterations?: number;
68
+ };
69
+ extensions: readonly ExtensionEntry[];
70
+ };
71
+
72
+ /** 缺省模型的**唯一**出处:identity 与调用方都读它,不各手抄一份(review 五轮 #3)。 */
73
+ export const CODING_DEFAULT_MODEL = { provider: "kimi", model: "kimi-k3" } as const;
74
+
75
+ /** 产品的身份 + 编码纪律,一条 prompt pack。 */
76
+ const ECHO_CODING_PROMPT = definePromptPack("echo:coding");
77
+
78
+ /**
79
+ * core 的 `echo:*` builtin 装上来的工具。产品层管不到它们,但它们同样决定被测行为,必须进 digest。
80
+ *
81
+ * **2026-08-31 从 4 件变成 9 件**:装配从低层 `new Agent()` 换成 `createEcho()` 之后,
82
+ * 这个 agent 拿到的是**完整 Runtime**——按状态根装了 skillStore 与 schedule,
83
+ * 于是 `echo:skills` / `echo:scheduler` 两条 builtin 有工具可注册。
84
+ * 原先那个窄工具集是低层装配的副产品,不是设计意图。
85
+ * 用户 2026-08-31 拍板接受这个变化(被测行为与 digest 都会变,不为它保留第二条装配路径)。
86
+ *
87
+ * **这里手写的名字由 `test/identity.test.ts` 的「与真 agent 工具集完全相等」断言守着**——
88
+ * core 增删任何一件 builtin 工具,该测试立刻红,不会静默漂移。
89
+ */
90
+ // **`ask_user` 不在这里**(2026-09-09):它只在「有人能答」时才装,而 `codingPreset()` 不设 `questions`
91
+ // ——评测就是没人能答的那一头,digest 记的正是被测的那份工具集。交互形态由 `mainFor()` 给 host,
92
+ // 那时真 agent 会多出这一件,与本清单的差异由使用方自己知道(identity 测的是 preset 这一份)。
93
+ const AGENT_BUILTIN_TOOLS = [
94
+ "TaskCreate",
95
+ "TaskGet",
96
+ "TaskList",
97
+ "TaskUpdate",
98
+ "subagent", // 2026-09-06 委派工具,core 恒装;子 agent 的样子由模型在调用时决定
99
+ "schedule_cancel",
100
+ "schedule_create",
101
+ "schedule_list",
102
+ "skill_activate",
103
+ "skill_create",
104
+ "tool_search", // 2026-09-02 渐进式披露的入口,core 恒装(在不在菜单上另算,这里是池)
105
+ "transcript_read",
106
+ // **会话面(`session_*`)不在这里**:挂不挂它是**容器**的决定(`CreateEchoOptions.sessions`),
107
+ // 不是产品身份。cli 开着它,所以真跑起来的 echo-coding 会多三件;而这份 digest 描述的是
108
+ // 「这个产品自己带什么」——把容器的选择写进产品身份,换个宿主就对不上了。
109
+ ] as const;
110
+
111
+ /** 产品自己出的四段(identity / conduct:coding / tool:workspace / tool:shell),按 order 排。 */
112
+ function productSections(): PromptSection[] {
113
+ return [codingIdentitySection(), codingConductSection(), workspaceToolsSection(), shellToolsSection()].sort((a, b) => a.order - b.order);
114
+ }
115
+
116
+ /** digest 用的固定装配上下文:产品四段都不引用变量,所以值无关紧要,只求确定。 */
117
+ const DIGEST_CONTEXT: AssembleContext = {
118
+ workspace: "/workspace",
119
+ model: { provider: CODING_DEFAULT_MODEL.provider, id: CODING_DEFAULT_MODEL.model },
120
+ agentId: "default",
121
+ sessionId: null,
122
+ };
123
+
124
+ /** 本 preset 的**行为身份快照**:把真正决定行为的东西一次性固定下来——产品自己出的 prompt 段逐字、缺省模型、
125
+ * 执行预算、**完整**工具集(产品层三件套 + Agent 构造期自带)。它是可复现的 digest 材料:
126
+ * 改任一段文本 / 换缺省模型 / 增删任一工具都会改 digest,两次结果一比就能判出静默漂移。
127
+ *
128
+ * **不在公共面**(不从 `index.ts` 导出):本仓没有生产消费者,它现在只给 `test/identity.test.ts`
129
+ * 当判据——手写的清单必须等于真装出来的工具集。 */
130
+ export function codingAgentIdentity(): {
131
+ sections: readonly { name: string; order: number; text: string }[];
132
+ defaultModel: string;
133
+ maxIterations: number;
134
+ toolNames: readonly string[];
135
+ } {
136
+ return {
137
+ sections: productSections().map((s) => {
138
+ const text = s.render(DIGEST_CONTEXT);
139
+ // 产品段都是字面量,同步返回;真变成异步了就是有人把读盘之类塞进了段——那不该属于 identity
140
+ if (typeof text !== "string") throw new Error(`prompt 段 '${s.name}' 的 render 不是同步的,不能进 digest`);
141
+ return { name: s.name, order: s.order, text };
142
+ }),
143
+ defaultModel: `${CODING_DEFAULT_MODEL.provider}/${CODING_DEFAULT_MODEL.model}`,
144
+ // 执行预算也决定成绩(review 六轮 P1):**读 core 的常量,不手抄**——core 改默认值,digest 跟着变
145
+ maxIterations: DEFAULT_MAX_ITERATIONS,
146
+ // shell / worktree / web 各组也从工厂取名:各 extension 注册的就是这份,不手写
147
+ toolNames: [...makeFsTools(), ...makeSearchTools(), ...makeShellTools(), ...makeWorktreeTools(), ...makeWebTools()]
148
+ .map((t) => t.name)
149
+ .concat(...AGENT_BUILTIN_TOOLS)
150
+ .sort(),
151
+ };
152
+ }
153
+
154
+ export function codingPreset(opts: CodingPresetOptions = {}): CodingPreset {
155
+ return {
156
+ agent: {
157
+ ...(opts.permission !== false ? { permission: permissionPolicyFor(opts.permission) } : {}),
158
+ ...(opts.skills !== undefined && opts.skills.length > 0 ? { skills: opts.skills } : {}),
159
+ ...(opts.maxIterations !== undefined ? { maxIterations: opts.maxIterations } : {}),
160
+ },
161
+ extensions: [
162
+ // 产品的身份与编码纪律
163
+ { entryId: "echo:coding", definition: ECHO_CODING_PROMPT, config: { sections: [codingIdentitySection(), codingConductSection()] } },
164
+ // fs / search 的工具是纯函数造出来的,可以在装配前就备好 → 走 `defineToolPack` 的 config;
165
+ // 它们的跨调用习惯段跟工具同一个 config 进来:工具卸了段也走
166
+ {
167
+ entryId: "echo:workspace",
168
+ definition: ECHO_WORKSPACE,
169
+ config: { tools: [...makeFsTools(), ...makeSearchTools()], sections: [workspaceToolsSection()] },
170
+ },
171
+ // bash 不行:它要 `agent.background`。所以 `echo:shell` 自己 inject 那条能力端口并在 apply 里
172
+ // 注册工具与段,这里只列 definition、不给 config(见 `extensions.ts` 的注释)。
173
+ { entryId: "echo:shell", definition: ECHO_SHELL },
174
+ // worktree 隔离要 `AgentRuntime.setWorkspace`,同 shell 一样自己 inject(2026-09-03)
175
+ { entryId: "echo:worktree", definition: ECHO_WORKTREE },
176
+ // 取网页 / 搜索:纯函数工具,config 进来;延迟工具,经 tool_search 取过才上菜单
177
+ { entryId: "echo:web", definition: ECHO_WEB, config: { tools: makeWebTools({ credentials: opts.credentials }) } },
178
+ ],
179
+ };
180
+ }
181
+
182
+ /** `bash` 单独造一把(不经 Extension)。给「自己给端口、自己注册」的低层 `new Agent()` 用。 */
183
+ export { makeBashTool };
package/src/cli.ts ADDED
@@ -0,0 +1,45 @@
1
+ // `echo-coding` 的命令行面:**用装配层的启动器部件把本产品跑起来**,自己只交一个 `Product`
2
+ // 和一个壳。
3
+ //
4
+ // 依赖方向(2026-09-09 拆包,记录见 `docs/decisions/implemented/2026-09-09-assembly-layer-packages.md`):
5
+ // `@echo-agent/core` ← `@echo-agent/base` ← {`@echo-agent/tui`, 各产品}。**产品之间平级**——
6
+ // 本包不依赖 `echo-agent`,那是它的兄弟不是它的上游。参数解析、凭据、引导设置、形态分叉、
7
+ // 装配、收摊全在 base 的 `mainFor()` 里,这里一行都不复制;交互形态起哪个壳由本文件挑
8
+ // (`terminalShell`),装配层不写死。
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
+ // 评测或别的宿主可以自己传——本产品不缺省开它。
15
+
16
+ import { readFileSync } from "node:fs";
17
+ import { conductEntry, mainFor, type Product } from "@echo-agent/base";
18
+ import { terminalShell } from "@echo-agent/tui";
19
+ import { codingPreset } from "./agent.ts";
20
+
21
+ /** 本包的版本,欢迎头里显示。`../package.json` 在源码树和 tarball 里都在这个相对位置。 */
22
+ const VERSION: string = (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string })
23
+ .version;
24
+
25
+ export const ECHO_CODING: Product = Object.freeze({
26
+ name: "echo-coding",
27
+ version: VERSION,
28
+ // 形态(`interactive`)本产品不看:两种形态的装配片段完全相同。workspace 不经 preset——
29
+ // 它是 session 级事实,`mainFor()` 直接交给 `createEcho()`(2026-09-01)。
30
+ //
31
+ // **执行预算 200**(2026-09-02 用户拍板):core 缺省 20 是通用 agent / 评测的预算,coding 在仓库里
32
+ // grep / read 几下就撞顶(实测 `[错误] 迭代上限 20`),每 20 步要人说一次「继续」。
33
+ // 评测的 identity 仍按 `codingPreset()` 缺省(20)算——产品与评测的预算不同,是否让 identity 跟产品走另议。
34
+ // 凭据 store 从形态里来(`web_search` 读 `brave`):与启动逻辑同一个文件,不另开
35
+ // 共用的纪律段由**产品**挂(2026-09-09 拍板):装配层不再恒挂,形态决定「有没有人能答」那一条。
36
+ // `codingPreset()` 自己只依赖 core,所以这一条加在这里,不加进它。
37
+ preset: (form, host) => {
38
+ const preset = codingPreset({ permission: false, maxIterations: 200, credentials: host.credentials });
39
+ return { ...preset, extensions: [conductEntry(form), ...preset.extensions] };
40
+ },
41
+ });
42
+
43
+ /** 进程入口的实质:`echo-agent` 的 `main` 绑上本产品。签名与它完全相同,退出码语义也相同。 */
44
+ // 壳由**产品**选(2026-09-09):装配层只认端口,这里挑终端那份实现。做 web / 桌面界面的产品换掉这一个参数即可。
45
+ export const main = mainFor(ECHO_CODING, terminalShell);
@@ -0,0 +1,121 @@
1
+ // coding agent 自己那几件工具的 Extension 形态:`echo:workspace` 与 `echo:shell`。
2
+ //
3
+ // **为什么不是直接 `registerTool()`**(2026-08-31 用户拍板:「机制必须同一份,都要走 extension」):
4
+ // 直调那条路没有 owner——装上去的工具没人持 disposer,卸不掉、也不出现在能力清单里。
5
+ // 走 Extension 之后,产品层的工具与内建、与第三方**同一个 `AgentTools.register`、同一份所有权账本**,
6
+ // 并且规格明写 first-party Extension「是公开扩展面是否够用的第一个 conformance consumer」——
7
+ // 我们自己先用一遍,扩展作者才不会撞上只有他们能看见的坑。
8
+ //
9
+ // **`defineToolPack` 来自 `@echo-agent/core/extension`,不在这里另抄一份**(review 二轮 P1):
10
+ // 上一版这里复制了 core 的实现,于是「注册中途撞名要整组回滚」那个修复得改两处——
11
+ // 复制一份实现就是复制一份将来会漏修的地方。
12
+
13
+ import { AgentBackgroundService, AgentPrompt, AgentRuntimeService, AgentTools, defineExtension, defineToolPack } from "@echo-agent/core/extension";
14
+ import { makeShellTools } from "./tools/bash.ts";
15
+ import { makeWorktreeTools } from "./tools/worktree.ts";
16
+ import { shellToolsSection } from "./prompt.ts";
17
+
18
+ /** 工作区读写与搜索:`read_file` / `write_file` / `edit_file` / `glob` / `grep` / `list_dir`。 */
19
+ export const ECHO_WORKSPACE = defineToolPack("echo:workspace");
20
+
21
+ /** 取网页与搜索:`web_fetch` / `web_search`(延迟工具)。纯函数造的工具,config 进来即可。 */
22
+ export const ECHO_WEB = defineToolPack("echo:web");
23
+
24
+ /**
25
+ * worktree 隔离:`worktree_enter` / `worktree_exit`(2026-09-03 用户拍板 B)。
26
+ * 与 `echo:shell` 同一个理由不用 `defineToolPack`:工具要 `AgentRuntime.setWorkspace`,那是 Agent 上的东西,
27
+ * 装配前拿不到——从 `AgentRuntimeService` 注入(`echo:agent` 恒 provide,排在所有扩展之前)。
28
+ */
29
+ export const ECHO_WORKTREE = defineExtension({
30
+ name: "echo:worktree",
31
+ hostAbiVersion: 1,
32
+ inject: {
33
+ tools: { service: AgentTools, required: true },
34
+ runtime: { service: AgentRuntimeService, required: true },
35
+ },
36
+ apply(ctx) {
37
+ const registry = ctx.get(AgentTools);
38
+ const tools = makeWorktreeTools({ runtime: ctx.get(AgentRuntimeService) });
39
+ void ctx.effect({
40
+ boundary: "turn",
41
+ start: () => {
42
+ const offs: (() => unknown)[] = [];
43
+ try {
44
+ for (const tool of tools) offs.push(registry.register(tool));
45
+ } catch (e) {
46
+ for (const off of offs.reverse()) void off();
47
+ throw e;
48
+ }
49
+ return {
50
+ value: tools.map((t) => t.name),
51
+ dispose: () => {
52
+ for (const off of offs.reverse()) void off();
53
+ },
54
+ };
55
+ },
56
+ });
57
+ },
58
+ });
59
+
60
+ /**
61
+ * 受权限管控的命令执行:`bash`。
62
+ *
63
+ * **它不用 `defineToolPack`,因为工具造不出来**:bash 要 `agent.background` 才支持
64
+ * `background: true`,而那是 Agent 实例上的东西——装配层在调 `createEcho()` 之前拿不到它。
65
+ * 上一版的做法是产品层自己 `new Agent()` 再自己 mount,也就是**第二个装配现场**。
66
+ *
67
+ * 现在换成从 `ctx` 拿:core 2026-08-31 把后台队列做成能力端口
68
+ * (`AgentBackgroundService`,见 `extension/registries.ts` 文件头)。于是本扩展变成
69
+ * 纯静态的一条 definition,装配层只管把它列进 `createEcho({ extensions })`。
70
+ *
71
+ * **`required: true`,不是 optional**(2026-08-31 review 三轮 P1 修正):上一版写的是
72
+ * `required: false`,理由是「没接后台队列照样能跑命令」——听起来合理,**但 ABI 里根本没有
73
+ * 读 optional 的方法**:`ctx.get()` 遇到没有 provider 的 optional 依赖直接抛
74
+ * (`fiber.ts` 的「optional 依赖 '…' 当前没有 provider」),扩展也无从先问一句「有没有」。
75
+ * 于是那个声明不是「优雅降级」,是**装不上**——review 实测复现。
76
+ *
77
+ * 改 required 之后语义反而更准:`agent.background` 是 **Agent 恒有的能力**
78
+ * (构造函数无条件造),所以任何由 Agent 造出来的 registries 都提供得了它。
79
+ * 走 `createEcho()` 恒有;自己搭 Host 而不传 `background` 就装不上本扩展,
80
+ * 报错明确指向缺的那条 Service——比装上一个「bash 在但后台不灵」的半残工具好。
81
+ *
82
+ * (`makeBashTool()` 的 `deps.background` 仍是可选:那是给「自己给端口、自己注册」的
83
+ * 低层 `new Agent()` 用的,与本扩展的装配前提是两件事。)
84
+ */
85
+ export const ECHO_SHELL = defineExtension({
86
+ name: "echo:shell",
87
+ hostAbiVersion: 1,
88
+ inject: {
89
+ tools: { service: AgentTools, required: true },
90
+ background: { service: AgentBackgroundService, required: true },
91
+ prompt: { service: AgentPrompt, required: true },
92
+ },
93
+ apply(ctx) {
94
+ const registry = ctx.get(AgentTools);
95
+ const prompt = ctx.get(AgentPrompt);
96
+ // bash + job_output / job_stop:同一张后台任务表(`agent.background`),一起装、一起撤
97
+ const tools = makeShellTools({ background: ctx.get(AgentBackgroundService) });
98
+ void ctx.effect({
99
+ // 与 `defineToolPack` 同一档:工具面每轮都可能变,声明得比实际需要强会挡住热重载
100
+ boundary: "turn",
101
+ start: () => {
102
+ // 工具与它们的习惯段(`tool:shell`)同一个 effect:一起装、一起撤。
103
+ // 中途撞名要把已注册的撤回去——半组工具在、半组不在,比整组不在更难排查
104
+ const offs: (() => unknown)[] = [];
105
+ try {
106
+ for (const tool of tools) offs.push(registry.register(tool));
107
+ offs.push(prompt.section(shellToolsSection()));
108
+ } catch (e) {
109
+ for (const off of offs.reverse()) void off();
110
+ throw e;
111
+ }
112
+ return {
113
+ value: tools.map((t) => t.name),
114
+ dispose: () => {
115
+ for (const off of offs.reverse()) void off();
116
+ },
117
+ };
118
+ },
119
+ });
120
+ },
121
+ });
package/src/index.ts ADDED
@@ -0,0 +1,17 @@
1
+ // `echo-coding` 公共面:coding agent **产品**——与 `echo-agent` 平级,互不依赖(2026-09-09 拆包)。
2
+ //
3
+ // **装配仍归 `createEcho()`,启动器部件归 `@echo-agent/base`**:`codingPreset()` 出配置;可执行文件
4
+ // `echo-coding` 是 base 的 `mainFor()` 绑上本产品与一个壳(`cli.ts`)。原先的 `createCodingAgent()`
5
+ // 自己造 Agent、造 Host、mount、收摊——那是第二个 composition root,2026-08-31 删掉了。
6
+
7
+ /** 可执行文件的实质:装配层的启动逻辑绑上本产品。`bin/echo-coding.ts` 调的就是它。 */
8
+ export { main, ECHO_CODING } from "./cli.ts";
9
+ export { codingPreset, CODING_DEFAULT_MODEL } from "./agent.ts";
10
+ 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";
16
+ export { permissionPolicyFor, DEFAULT_PERMISSION } from "./permission.ts";
17
+ export type { PermissionPolicy, PermissionRule } from "./permission.ts";
@@ -0,0 +1,64 @@
1
+ // 权限:产品策略翻译成 core 的 authorization stage,不再是一条 preToolUse hook。
2
+ //
3
+ // 三档规则不变:allow(放行)/ deny(拒)/ ask(问裁决人)。规则在构造期交给 Agent
4
+ // (`permissionPolicyFor()` → `AgentOptions.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` 只声明**有没有人会答**,不自己找人答。
13
+ //
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";
20
+
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
+ };
37
+
38
+ /**
39
+ * 缺省策略:读随便;**bash / write_file / edit_file 先问**,其余放行——与 Claude Code 的缺省一个精神。
40
+ * 这是一张黑名单而不是白名单(2026-09-09 拍板,`docs/decisions/implemented/2026-09-09-default-permission-blacklist.md`):
41
+ * 「其余」里也有动东西的,各有各的不问的理由——worktree_enter 开的是新分支与新目录,可逆;worktree_exit 的删除
42
+ * 由 git 自己挡(有未提交改动就拒,分支保留);web_fetch / web_search 出网不问(2026-09-03 拍板);core 内建的
43
+ * 记忆 / 任务 / 技能 / 闹钟写的是 agent 自己的状态,不是用户的世界。要更严的产品自己给 `rules`。
44
+ * bash 不受工作区边界约束,它靠的正是这一条 ask。
45
+ */
46
+ export const DEFAULT_PERMISSION: PermissionPolicy = {
47
+ rules: { bash: "ask", write_file: "ask", edit_file: "ask" },
48
+ fallback: "allow",
49
+ };
50
+
51
+ /** 把产品策略翻译成 core 的 stage 策略——构造期交给 `new Agent({ permission })`。 */
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
+ };
64
+ }
package/src/prompt.ts ADDED
@@ -0,0 +1,43 @@
1
+ // echo-coding 自己拥有的 prompt 段(2026-09-01 拍定,决策见 memory `prompt-design-decisions-2026-09-01`):
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 装不下的「几个工具怎么选」。
6
+ // 文本是模型逐字读的资产,全英文;改动这里 = 改被测行为(`codingAgentIdentity()` 的 digest 会变)。
7
+ // `tool:shell` 里的 120 s、`background: true`、非零退出码走 error,都是 `tools/bash.ts` 的**真实行为**——
8
+ // 行为变了这段跟着改,不许两边说的不一样。
9
+
10
+ import { PROMPT_ORDER, type PromptSection } from "@echo-agent/core";
11
+
12
+ export const CODING_IDENTITY =
13
+ "You are Echo Coding, a coding agent working inside the user's repository. You read, change, and verify code on the user's behalf, and you work for one user across many sessions.";
14
+
15
+ export const CODING_CONDUCT = `# Working in code
16
+ - Understand the code around a change before making it.
17
+ - Follow the conventions already in the repository: naming, structure, formatting, test style, package manager.
18
+ - Change only what the task requires. No drive-by refactors, no speculative abstractions, no compatibility shims for code you can simply change.
19
+ - 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
+ - Do not commit, push, or publish unless the user asks.
21
+ - Add a comment only for a constraint the code cannot show; do not restate the code.`;
22
+
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
+ export function codingIdentitySection(): PromptSection {
30
+ return { name: "identity", order: PROMPT_ORDER.identity, render: () => CODING_IDENTITY };
31
+ }
32
+
33
+ export function codingConductSection(): PromptSection {
34
+ return { name: "conduct:coding", order: PROMPT_ORDER.conduct + 1, render: () => CODING_CONDUCT };
35
+ }
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
+ }