@echo-agent/coding 0.2.0 → 0.4.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,24 +1,23 @@
1
1
  # @echo-agent/coding
2
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.
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.
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
8
8
  > package.
9
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.
10
+ > **Status: `0.x`.** Until `1.0`, a minor version may contain breaking changes.
12
11
 
13
12
  ## Run it
14
13
 
15
14
  ```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
15
+ bun add -g @echo-agent/coding
16
+ MOONSHOT_API_KEY=sk-... echo-coding
20
17
  ```
21
18
 
19
+ Or run it once without installing: `bunx --package @echo-agent/coding echo-coding`.
20
+
22
21
  The command name stays `echo-coding` even though the package is scoped — the unscoped name was
23
22
  already taken on npm by an unrelated project.
24
23
 
@@ -31,10 +30,11 @@ conversation even in the same directory.
31
30
 
32
31
  ## What this package is
33
32
 
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.
33
+ 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.
38
38
 
39
39
  Full documentation is in the
40
40
  [repository README](https://github.com/echo-yiyi/echo-agent#readme).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@echo-agent/coding",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "description": "Echo's coding agent: file, search, shell and web tools, its own identity and conduct. Installs the `echo-coding` command. Requires Bun.",
@@ -8,9 +8,9 @@
8
8
  "echo-coding": "./bin/echo-coding.ts"
9
9
  },
10
10
  "dependencies": {
11
- "@echo-agent/base": "0.2.0",
12
- "@echo-agent/core": "0.2.0",
13
- "@echo-agent/tui": "0.2.0"
11
+ "@echo-agent/base": "0.4.0",
12
+ "@echo-agent/core": "0.4.0",
13
+ "@echo-agent/tui": "0.4.0"
14
14
  },
15
15
  "devDependencies": {
16
16
  "@types/bun": "latest",
package/src/agent.ts CHANGED
@@ -96,12 +96,14 @@ const AGENT_BUILTIN_TOOLS = [
96
96
  "TaskList",
97
97
  "TaskUpdate",
98
98
  "subagent", // 2026-09-06 委派工具,core 恒装;子 agent 的样子由模型在调用时决定
99
+ "extension_reload", // 2026-09-14 模型自己触发热部署;`createEcho()` 有扩展目录可扫就装(低层没有)
99
100
  "schedule_cancel",
100
101
  "schedule_create",
101
102
  "schedule_list",
102
103
  "skill_activate",
103
104
  "skill_create",
104
105
  "tool_search", // 2026-09-02 渐进式披露的入口,core 恒装(在不在菜单上另算,这里是池)
106
+ "tool_output_read", // 2026-11-02 大工具结果外存之后的读回,core 恒装、常驻菜单
105
107
  "transcript_read",
106
108
  // **会话面(`session_*`)不在这里**:挂不挂它是**容器**的决定(`CreateEchoOptions.sessions`),
107
109
  // 不是产品身份。cli 开着它,所以真跑起来的 echo-coding 会多三件;而这份 digest 描述的是
@@ -179,5 +181,5 @@ export function codingPreset(opts: CodingPresetOptions = {}): CodingPreset {
179
181
  };
180
182
  }
181
183
 
182
- /** `bash` 单独造一把(不经 Extension)。给「自己给端口、自己注册」的低层 `new Agent()` 用。 */
184
+ /** `bash` 单独造一把(不经 Extension)。`makeShellTools()` 与测试都从这里造。 */
183
185
  export { makeBashTool };
package/src/cli.ts CHANGED
@@ -14,7 +14,7 @@
14
14
  // 评测或别的宿主可以自己传——本产品不缺省开它。
15
15
 
16
16
  import { readFileSync } from "node:fs";
17
- import { conductEntry, mainFor, type Product } from "@echo-agent/base";
17
+ import { conductEntry, mainFor, retainRecentDays, type Product } from "@echo-agent/base";
18
18
  import { terminalShell } from "@echo-agent/tui";
19
19
  import { codingPreset } from "./agent.ts";
20
20
 
@@ -38,6 +38,8 @@ export const ECHO_CODING: Product = Object.freeze({
38
38
  const preset = codingPreset({ permission: false, maxIterations: 200, credentials: host.credentials });
39
39
  return { ...preset, extensions: [conductEntry(form), ...preset.extensions] };
40
40
  },
41
+ // 观测留 30 天(2026-09-15 用户拍板,与 echo-agent 同一条规则;两个产品平级,各自声明各自的)。
42
+ observationExpiry: retainRecentDays(30),
41
43
  });
42
44
 
43
45
  /** 进程入口的实质:`echo-agent` 的 `main` 绑上本产品。签名与它完全相同,退出码语义也相同。 */
package/src/extensions.ts CHANGED
@@ -6,11 +6,12 @@
6
6
  // 并且规格明写 first-party Extension「是公开扩展面是否够用的第一个 conformance consumer」——
7
7
  // 我们自己先用一遍,扩展作者才不会撞上只有他们能看见的坑。
8
8
  //
9
- // **`defineToolPack` 来自 `@echo-agent/core/extension`,不在这里另抄一份**(review 二轮 P1):
9
+ // **`defineToolPack` 与 `registerAll` 都来自 `@echo-agent/core/extension`,不在这里另抄一份**(review 二轮 P1;
10
+ // 2026-09-14 `registerAll` 导出后,下面两条扩展手抄的逆序撤销也换成了它):
10
11
  // 上一版这里复制了 core 的实现,于是「注册中途撞名要整组回滚」那个修复得改两处——
11
12
  // 复制一份实现就是复制一份将来会漏修的地方。
12
13
 
13
- import { AgentBackgroundService, AgentPrompt, AgentRuntimeService, AgentTools, defineExtension, defineToolPack } from "@echo-agent/core/extension";
14
+ import { AgentBackgroundService, AgentPrompt, AgentRuntimeService, AgentTools, defineExtension, defineToolPack, registerAll } from "@echo-agent/core/extension";
14
15
  import { makeShellTools } from "./tools/bash.ts";
15
16
  import { makeWorktreeTools } from "./tools/worktree.ts";
16
17
  import { shellToolsSection } from "./prompt.ts";
@@ -38,21 +39,8 @@ export const ECHO_WORKTREE = defineExtension({
38
39
  const tools = makeWorktreeTools({ runtime: ctx.get(AgentRuntimeService) });
39
40
  void ctx.effect({
40
41
  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
- },
42
+ // 中途撞名整组撤回、卸载逆序全撤:`registerAll`,与内建同一份
43
+ start: () => registerAll(tools.map((tool) => () => registry.register(tool))),
56
44
  });
57
45
  },
58
46
  });
@@ -68,19 +56,15 @@ export const ECHO_WORKTREE = defineExtension({
68
56
  * (`AgentBackgroundService`,见 `extension/registries.ts` 文件头)。于是本扩展变成
69
57
  * 纯静态的一条 definition,装配层只管把它列进 `createEcho({ extensions })`。
70
58
  *
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` 就装不上本扩展,
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 装不上,
80
64
  * 报错明确指向缺的那条 Service——比装上一个「bash 在但后台不灵」的半残工具好。
81
65
  *
82
- * (`makeBashTool()` 的 `deps.background` 仍是可选:那是给「自己给端口、自己注册」的
83
- * 低层 `new Agent()` 用的,与本扩展的装配前提是两件事。)
66
+ * (`makeBashTool()` 的 `deps.background` 仍是可选:单独造工具、不接后台队列时 `background: true` 不可用,
67
+ * 与本扩展的装配前提是两件事。)
84
68
  */
85
69
  export const ECHO_SHELL = defineExtension({
86
70
  name: "echo:shell",
@@ -98,24 +82,9 @@ export const ECHO_SHELL = defineExtension({
98
82
  void ctx.effect({
99
83
  // 与 `defineToolPack` 同一档:工具面每轮都可能变,声明得比实际需要强会挡住热重载
100
84
  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
- },
85
+ // 工具与它们的习惯段(`tool:shell`)同一个 effect:一起装、一起撤。
86
+ // 中途撞名要把已注册的撤回去——半组工具在、半组不在,比整组不在更难排查(`registerAll`,与内建同一份)
87
+ start: () => registerAll([...tools.map((tool) => () => registry.register(tool)), () => prompt.section(shellToolsSection())]),
119
88
  });
120
89
  },
121
90
  });
package/src/permission.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  // 权限:产品策略翻译成 core 的 authorization stage,不再是一条 preToolUse hook。
2
2
  //
3
3
  // 三档规则不变:allow(放行)/ deny(拒)/ ask(问裁决人)。规则在构造期交给 Agent
4
- // (`permissionPolicyFor()` → `AgentOptions.permission`),跑在固定 stage:
4
+ // (`permissionPolicyFor()` → `EchoAgentOptions.permission`),跑在固定 stage:
5
5
  // transform hooks → 重新校验 → freeze → authorization → execute。裁决看到的是冻结后的最终参数,
6
6
  // 人批准的和工具执行的是同一份;hook 在它之后改不了参数。
7
7
  //
@@ -48,7 +48,7 @@ export const DEFAULT_PERMISSION: PermissionPolicy = {
48
48
  fallback: "allow",
49
49
  };
50
50
 
51
- /** 把产品策略翻译成 core 的 stage 策略——构造期交给 `new Agent({ permission })`。 */
51
+ /** 把产品策略翻译成 core 的 stage 策略——构造期经 `createEcho({ agent: { permission } })` 交给 core。 */
52
52
  export function permissionPolicyFor(policy: PermissionPolicy = DEFAULT_PERMISSION): CorePermissionPolicy {
53
53
  return {
54
54
  authorize: ({ toolName }) => {
package/src/tools/bash.ts CHANGED
@@ -12,7 +12,12 @@ import { spawn, type ChildProcess } from "node:child_process";
12
12
  import { existsSync } from "node:fs";
13
13
  import { toolError, toolOk, type AgentBackground, type AgentToolResult, type ModelTool } from "@echo-agent/core";
14
14
 
15
- const OUTPUT_CAP = 30_000;
15
+ /**
16
+ * 前台命令最多收这么多字符(2026-11-02):不再在这里截到 30,000 丢掉后半——报错多在末尾。
17
+ * 收全了交给 core:超过内联上限时全文外存、对话里只留头尾预览(`@echo-agent/core` 的工具结果外存)。
18
+ * 这个上限只防内存失控。
19
+ */
20
+ const CAPTURE_CAP = 8 * 1024 * 1024;
16
21
  const DEFAULT_TIMEOUT_MS = 120_000;
17
22
  /** job_output 缺省回读的字符数:够看清最近的日志,又不至于一次把缓冲全倒进上下文。 */
18
23
  const JOB_TAIL_DEFAULT = 4_000;
@@ -217,7 +222,7 @@ function runForeground(
217
222
  let tail = ""; // 末尾几百字节单独留着:cwd 标记在这里找,输出被截断也丢不了
218
223
  const append = (chunk: string): void => {
219
224
  tail = (tail + chunk).slice(-CWD_TAIL_KEEP);
220
- if (out.length >= OUTPUT_CAP) {
225
+ if (out.length >= CAPTURE_CAP) {
221
226
  truncated = true;
222
227
  return;
223
228
  }
@@ -248,8 +253,8 @@ function runForeground(
248
253
  const marked = CWD_MARK_RE.exec(tail);
249
254
  const newCwd = marked?.[1];
250
255
  const body = marked === null ? out : out.replace(CWD_MARK_RE, "").replace(/\n$/, "");
251
- let text = body.slice(0, OUTPUT_CAP);
252
- if (truncated || body.length > OUTPUT_CAP) text += `\n…[output truncated: over ${OUTPUT_CAP} characters]`;
256
+ let text = body.slice(0, CAPTURE_CAP);
257
+ if (truncated || body.length > CAPTURE_CAP) text += `\n…[output truncated: over ${CAPTURE_CAP} characters]`;
253
258
  const withCwd = (r: AgentToolResult): AgentToolResult & { cwd?: string } => (newCwd === undefined ? r : { ...r, cwd: newCwd });
254
259
  if (spawnError !== undefined) {
255
260
  resolvePromise(toolError(`The command could not start: ${spawnError}`));
package/src/tools/fs.ts CHANGED
@@ -13,6 +13,7 @@
13
13
  import { mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
14
14
  import { dirname, isAbsolute, resolve, sep } from "node:path";
15
15
  import { toolError, toolOk, type ModelTool, type ToolExecutionContext } from "@echo-agent/core";
16
+ import { isImagePath, loadImageFile } from "@echo-agent/base";
16
17
 
17
18
  /** 读回显的上限:超过就截断并标注——一个 50MB 的日志不该挤爆上下文。 */
18
19
  const READ_CAP = 50_000;
@@ -98,8 +99,11 @@ function readFileTool(seen: SeenFiles): ModelTool<{ path: string; offset?: numbe
98
99
  label: "读文件",
99
100
  // 只读:模型一口气读五个文件时同批同跑。`seen` 只按路径记一条 mtime,同批互不覆盖。
100
101
  concurrent: true,
102
+ // 自己会分页(行数 + `READ_CAP` 截断并教 offset/limit),不走 core 的外存——外存再读一遍是绕路(2026-11-02,同 Claude Code 的 Read)
103
+ maxInlineTokens: Infinity,
101
104
  description:
102
- "Read a file with line numbers. Use offset/limit to read a large file in parts. Read a file before editing it.",
105
+ "Read a file with line numbers. Use offset/limit to read a large file in parts. Read a file before editing it. " +
106
+ "PNG, JPEG, GIF and WebP files are returned as images you can see; large ones are scaled down first.",
103
107
  parameters: {
104
108
  type: "object",
105
109
  properties: {
@@ -112,6 +116,19 @@ function readFileTool(seen: SeenFiles): ModelTool<{ path: string; offset?: numbe
112
116
  async execute({ path, offset, limit }, ctx) {
113
117
  const abs = await resolveSafe(ctx, path);
114
118
  if (abs === null) return toolError(`Path outside the workspace: '${path}'`);
119
+ // 图片按图片返回(2026-11-02,照 Claude Code 的 Read):大了先缩放。文件不存在、或扩展名是图片但内容不是,
120
+ // 落到下面照文本读(不存在就报 File not found)
121
+ if (isImagePath(abs)) {
122
+ const loaded = await loadImageFile(abs);
123
+ if (loaded.ok) {
124
+ const { width, height } = loaded.info;
125
+ const scaled = loaded.original === undefined ? "" : `, scaled down from ${loaded.original.width}×${loaded.original.height}`;
126
+ return toolOk(`Image file ${path} (${width}×${height}${scaled})`, { path, width, height }, [loaded.image]);
127
+ }
128
+ if (loaded.reason === "too_large") {
129
+ return toolError(`Cannot read ${path} as an image: ${loaded.message}. Make a smaller copy (for example with ImageMagick via bash) and read that.`);
130
+ }
131
+ }
115
132
  let raw: string;
116
133
  try {
117
134
  raw = await readFile(abs, "utf8");
@@ -70,6 +70,8 @@ function enterTool(deps: WorktreeDeps, state: WorktreeState): ModelTool<{ name?:
70
70
  kind: "model",
71
71
  name: "worktree_enter",
72
72
  label: "进 worktree",
73
+ // 切的是父 agent 的 workspace:子 agent 调一下父就跟着换了目录(2026-09-14 拍板:不可委派)
74
+ delegable: false,
73
75
  description:
74
76
  "Create a git worktree for this repository at .echo/worktrees/<name> on a new branch <name> (from the current HEAD) " +
75
77
  "and make it the workspace: from then on file tools, search and bash resolve paths there, while the original checkout " +
@@ -116,6 +118,7 @@ function exitTool(deps: WorktreeDeps, state: WorktreeState): ModelTool<{ remove?
116
118
  name: "worktree_exit",
117
119
  label: "出 worktree",
118
120
  deferred: true,
121
+ delegable: false,
119
122
  description:
120
123
  "Leave the worktree entered with worktree_enter: the workspace goes back to the main checkout. " +
121
124
  "With remove: true the worktree directory is deleted afterwards (git refuses while it has uncommitted changes); " +