skyloom 1.16.2 → 1.17.0

package/docs/OPTIMIZATION_PLAN.md

@@ -120,13 +120,13 @@
 
 - [x] **P4.1 Session 恢复 + 持久化修复**：新增 CLI `/sessions`（编号列表、标记当前）、`/resume <序号|id>`、`/new`。**并修复了一个严重 bug**：`persistDb()`（唯一写盘的代码）**从未被调用** → sql.js 纯内存 → 会话/长期记忆/工作记忆**重启全丢**（"启动自动恢复最新会话"形同虚设）。改为所有写经 `dbRun` 触发**防抖落盘** + `close()` 同步保存。新增跨实例持久化回归测试。
 - [x] **P4.2 自动压缩（catalog 感知触发）**：`shouldAutoCompact()`/`contextUsage()` 不再硬编码 128K —— 改为按当前模型在 catalog 里的真实 `context` 窗口判断（留 20% 余量给回复）。修复了小窗口模型（deepseek-reasoner 64K、mixtral 32K）长聊时**先于压缩就溢出**的隐患；状态栏 % 与模型名也正确了。压缩本身（摘要 + 保留近 N 条 + 指令保真）已存在并已接线。后续：结构化 checkpoint + 溢出后重试（对标 opencode）。
-- [ ] **P4.3 上下文快照**：环境信息、日期、工作区、激活技能合成一份"系统上下文"，模型可见但与历史分离（轻量版 Context Epoch）。
+- [x] **P4.3 环境上下文快照**（对标 Claude Code `<env>` 块）：[`envcontext.ts`](../src/core/envcontext.ts) 的 `buildEnvBlock` 合成「运行环境」块(工作目录、平台、Node、git 仓库/分支、日期),`gitInfo` 用纯文件读取识别仓库与分支(兼容 worktree 的 `.git` 文件)。`BaseAgent.injectEnvironment` 在 init/reinitLanguage 把它注入系统提示,与对话历史分离。新增 [`tests/envcontext.test.ts`](../tests/envcontext.test.ts) 6 用例。
 
 ### Phase 5 — 工具与插件健壮性｜~1 天
 
-- [ ] **P5.1 工具 IO 校验**：工具定义带 input/output schema，非法输入不执行、非法输出不算成功（对标 opencode `tools.md`）。
-- [ ] **P5.2 权限内聚**：危险操作的 `permission.assert` 由工具自身发起，security 模块只评估策略 + 管理审批，统一 `ask/allow/deny` 语义。
-- [ ] **P5.3 插件 hook**：目录加载器升级为有序 hook（`init` / `tool.register` / `provider.update`），插件在自己的 scope 注册，卸载即移除。
+- [x] **P5.1 工具输入校验 + 强制 coercion**（对标 opencode `tools.md`）：`ToolRegistry.validateAndCoerce` 在 `execute` 里于缓存/执行**之前**校验并归一化入参 —— 必填项缺失即拒、按声明类型 coerce（`"5"`→5、`"true"`→true、JSON 串→array/object）、enum 成员校验，handler 收到的是干净的类型化值，非法输入返回**可操作的**错误供模型重试。修了 `parseInt` 截断浮点(`"3.5"`→3)的隐患。见 [`tests/tool.test.ts`](../tests/tool.test.ts)（+7 用例）。输出校验暂未做。
+- [x] **P5.2 权限模式内聚**（对标 Claude Code 权限模式）：把审批逻辑收敛为一个纯函数 `decideApproval(level, mode, tool) → allow/ask/deny`（[security.ts](../src/core/security.ts)），`checkApproval` 只做红线门禁 + 调用它 + 回调。新增模式 `acceptEdits`（自动放行文件编辑类工具,其余照 default 询问）与 `bypass`（除红线外全放行）;保留 `auto/interactive/strict` 行为不变。`/perm <default|auto|accept|strict|bypass>` 运行时切换(linear + loom),`config.cli.approvalMode` 启动时生效。新增 [`tests/security.test.ts`](../tests/security.test.ts) 11 用例覆盖决策矩阵。后续:让工具自身发起 `permission.assert`(细粒度 scope)。
+- [x] **P5.3 插件 hook 生命周期**（对标 opencode 插件）：[`plugins/loader.ts`](../src/plugins/loader.ts) 从扁平加载器升级为有序 hook 系统。插件导出 `activate(ctx)`,通过 `ctx.registerTool` / `ctx.on(hook, fn)` 在**自己的 scope** 注册;`unload(name)` 精确移除其工具与 hook handler(并调 `deactivate`)。核心 hook:`init`(加载后、agent 起来前由 `SystemContext.initAll` 触发)、`tool.register`、`provider.update`。handler 按注册顺序触发、单个抛错隔离。**保留 legacy `register(registry)`**(diff 注册表追踪其工具以支持卸载)。新增 [`tests/plugins.test.ts`](../tests/plugins.test.ts) 7 用例。后续:`provider.update` 在 model_config 变更处触发。
 
 ### Phase 6 — 测试与质量门禁｜~1.5 天
 
@@ -176,3 +176,20 @@ M5 打磨成品     Phase 7        → 美学工程化 + 品牌资产 + 发布
 | 流式与工具执行交错复杂 | 复用已存在的 `chatStreamImpl` 事件模型，只接线不重写 |
 | Catalog 迁移漏模型 | 以 `config/models.yaml` 为真值源迁移，向导/README 派生 |
 | 美学改动破坏现有观感 | 设计 token 抽取为"提取"非"重画"，先快照对比 |
+
+---
+
+## 6. Phase 8 — Claude Code / opencode 能力对齐 ✅ 已完成
+
+四项核心能力补齐,全部 `tsc --noEmit` 绿 + 单测覆盖(351 → 387 用例,+36):
+
+- [x] **P8.1 通用可定义子智能体**(对标 Claude Code `Task` 工具)
+  [`src/core/subagent.ts`](../src/core/subagent.ts) + [`src/tools/spawn.ts`](../src/tools/spawn.ts):`spawn_agent` 工具派生**隔离上下文**的子智能体(独立临时记忆,用完即删),只回传最终报告。内置 `general-purpose` / `explore`;支持 `.sky/agents/*.md` 与 `.claude/agents/*.md` 自定义(frontmatter 兼容 Claude Code,工具名自动映射)。子智能体永不持有 `spawn_agent`(无递归)。`/agents` 列举。新增 [`tests/subagent.test.ts`](../tests/subagent.test.ts) 13 用例。
+- [x] **P8.2 精确编辑 + diff**(对标 Claude Code `Edit`)
+  [`src/core/diff.ts`](../src/core/diff.ts) + 升级 `edit_file`:强制**唯一匹配**(歧义即拒)、`replace_all`、no-op 检测、返回统一 diff(+/- 统计)。并修复旧实现 `String.replace` 把 `$&`/`$1` 当替换模式的隐患。新增 [`tests/edit_diff.test.ts`](../tests/edit_diff.test.ts) 10 用例。
+- [x] **P8.3 后台任务 / 长进程**(对标 Claude Code Bash `run_in_background`)
+  [`src/core/bgproc.ts`](../src/core/bgproc.ts):`run_bash` 加 `background=true` 派后台子进程,`bash_output`(增量读)/`list_bash`/`kill_bash` 控制。复用沙箱红线预检;滚动输出上限;会话退出 `killAll`(无孤儿)。新增 [`tests/bgproc.test.ts`](../tests/bgproc.test.ts) 5 用例。
+- [x] **P8.4 诊断(LSP 关键能力)**(对标 opencode LSP)
+  [`src/core/diagnostics.ts`](../src/core/diagnostics.ts) + `get_diagnostics` 工具:TS/JS 经**工作区** TypeScript 编译器 API 取真实语义诊断(行:列 + TS 码),零额外安装;其他语言走 `config.diagnostics` 配置的外部 checker(解析 `file:line:col` 输出)。新增 [`tests/diagnostics.test.ts`](../tests/diagnostics.test.ts) 8 用例。
+
+> 这是把"完整的多 Agent 终端"推进到**与 Claude Code / opencode 同代能力面**的一步:可派生子智能体、精确可审计的编辑、后台进程、按文件诊断闭环。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skyloom",
-  "version": "1.16.2",
+  "version": "1.17.0",
   "description": "天空织机 Skyloom — 6 weather-themed AI agents: Fog, Rain, Frost, Snow, Dew, Fair",
   "preferGlobal": true,
   "type": "commonjs",

package/src/cli/loom_chat.ts

@@ -424,6 +424,17 @@ export async function loomChat(ctx: any, startAgent: any, deps: LoomChatDeps): P
         dim(`模式 → ${mode.current}${mode.current === "default" ? "" : " · Shift+Tab 或 /default 切回"}`);
         continue;
       }
+      if (cmdL === "/perm" || cmdL.startsWith("/perm ")) {
+        const { getSecurity, PERMISSION_MODE_ALIASES } = require("../core/security");
+        const sec = getSecurity();
+        const arg = inp.split(/\s+/)[1]?.toLowerCase();
+        if (!arg) { dim(`权限模式: ${sec.approvalMode} · 可选 default | auto | accept | strict | bypass`); continue; }
+        const m = PERMISSION_MODE_ALIASES[arg];
+        if (!m) { dim(`未知权限模式 '${arg}' · 可选 default | auto | accept | strict | bypass`); continue; }
+        sec.setMode(m);
+        dim(`✓ 权限模式 → ${m}`);
+        continue;
+      }
       if (cmdL === "/context") {
         try {
           const d = agent.contextDetail();

package/src/cli/main.ts

@@ -303,8 +303,14 @@ async function chat(agentName: string, modelOverride?: string, classic?: boolean
 
   // Wire up security approval — prompt user for HIGH/CRITICAL operations
   try {
-    const { getSecurity, DangerLevel } = require("../core/security");
+    const { getSecurity, DangerLevel, PERMISSION_MODE_ALIASES } = require("../core/security");
     const sec = getSecurity();
+    // Honor a configured permission mode (config.yaml cli.approvalMode), mapped
+    // through the same aliases as /perm.
+    const cfgMode = (ctx as any).config?.cli?.approvalMode || (ctx as any).config?.cli?.approval_mode;
+    if (cfgMode && PERMISSION_MODE_ALIASES[String(cfgMode).toLowerCase()]) {
+      sec.setMode(PERMISSION_MODE_ALIASES[String(cfgMode).toLowerCase()]);
+    }
     sec.setApprovalCallback(async (tool: string, args: Record<string, any>, level: number) => {
       process.stdout.write(chalk.yellow(`\n  ⚠ ${tool} ( danger level ${level} )\n`));
       process.stdout.write(chalk.dim(`     args: ${JSON.stringify(args).slice(0, 80)}\n`));
@@ -415,6 +421,17 @@ async function chat(agentName: string, modelOverride?: string, classic?: boolean
       process.stdout.write(chalk.dim(`  模式 → ${MODE.current} · ${MODE.describe()}\n`));
       continue;
     }
+    if (cmdL === "/perm" || cmdL.startsWith("/perm ")) {
+      const { getSecurity, PERMISSION_MODE_ALIASES } = require("../core/security");
+      const sec = getSecurity();
+      const arg = inp.split(/\s+/)[1]?.toLowerCase();
+      if (!arg) { process.stdout.write(chalk.dim(`  权限模式: ${sec.approvalMode} · 可选 default | auto | accept | strict | bypass\n`)); continue; }
+      const m = PERMISSION_MODE_ALIASES[arg];
+      if (!m) { process.stdout.write(chalk.yellow(`  未知权限模式 '${arg}' · 可选 default | auto | accept | strict | bypass\n`)); continue; }
+      sec.setMode(m);
+      process.stdout.write(chalk.green(`  ✓ 权限模式 → ${m}\n`));
+      continue;
+    }
     if (cmdL === "/context") {
       try {
         const d = currentAgent.contextDetail();
@@ -438,6 +455,19 @@ async function chat(agentName: string, modelOverride?: string, classic?: boolean
       process.stdout.write("\n");
       continue;
     }
+    if (cmdL === "/agents") {
+      const { loadSubagentDefinitions } = require("../core/subagent");
+      const defs = loadSubagentDefinitions();
+      process.stdout.write(chalk.bold(`\n  可派生子智能体 · spawn_agent\n`));
+      for (const d of defs.values()) {
+        const scope = d.source === "builtin" ? "内置" : "自定义";
+        const tools = d.tools === null ? "全部工具" : `${d.tools.length} 个工具`;
+        process.stdout.write(chalk.dim(`  ◇ ${String(d.name).padEnd(18)} ${d.description}\n`));
+        process.stdout.write(chalk.dim(`    └ ${scope} · ${tools}${d.model ? ` · ${d.model}` : ""}\n`));
+      }
+      process.stdout.write(chalk.dim(`\n  自定义: 在 .sky/agents/ 或 .claude/agents/ 放 <name>.md (frontmatter: description/tools/model)\n\n`));
+      continue;
+    }
     if (cmdL === "/trace") {
       const trace = (currentAgent as any).getLastTrace?.();
       if (!trace || !trace.spans?.length) { process.stdout.write(chalk.dim("  本会话还没有可追踪的运行\n")); continue; }

package/src/core/agent.ts

@@ -166,6 +166,17 @@ export class BaseAgent {
     }
   }
 
+  /** Consolidated environment snapshot (cwd/platform/git/date) — see envcontext. */
+  protected injectEnvironment(prompt: string): string {
+    try {
+      const { buildEnvBlock } = require('./envcontext');
+      const lang = (this.config as any).llm?.language || 'zh';
+      return prompt + '\n\n' + buildEnvBlock({ lang });
+    } catch {
+      return prompt;
+    }
+  }
+
   /** Always return the live current time — never stale. */
   protected currentTimeTag(): string {
     const date = new Date();
@@ -229,6 +240,7 @@ export class BaseAgent {
     this._baseSystemPrompt = '';
     this._baseSystemPrompt = this.resolveSystemPrompt();
     this._baseSystemPrompt = this.injectWorkspaceInfo(this._baseSystemPrompt);
+    this._baseSystemPrompt = this.injectEnvironment(this._baseSystemPrompt);
     this._baseSystemPrompt = this.injectBehaviorRules(this._baseSystemPrompt);
     this._baseSystemPrompt = this.injectProgrammingWisdom(this._baseSystemPrompt);
     this._baseSystemPrompt = this.injectProjectMemory(this._baseSystemPrompt);
@@ -254,6 +266,7 @@ export class BaseAgent {
 
     this._baseSystemPrompt = this.resolveSystemPrompt();
     this._baseSystemPrompt = this.injectWorkspaceInfo(this._baseSystemPrompt);
+    this._baseSystemPrompt = this.injectEnvironment(this._baseSystemPrompt);
     this._baseSystemPrompt = this.injectBehaviorRules(this._baseSystemPrompt);
     this._baseSystemPrompt = this.injectProgrammingWisdom(this._baseSystemPrompt);
     this._baseSystemPrompt = this.injectProjectMemory(this._baseSystemPrompt);

package/src/core/bgproc.ts

@@ -0,0 +1,153 @@
+/**
+ * Background process manager — long-running shells that don't block the agent.
+ *
+ * `run_bash` with background=true spawns a child here and returns immediately
+ * with a job id. The agent later pulls incremental output (bash_output), lists
+ * jobs (list_bash), or terminates one (kill_bash). Children are NOT detached,
+ * so they die with the sky process — no orphan management needed across runs.
+ */
+
+import { spawn, type ChildProcess, execSync } from 'child_process';
+import { getLogger } from './logger';
+import { preflightCheck } from './sandbox';
+
+const log = getLogger('bgproc');
+
+/** Per-job rolling output cap — keep the tail, drop the oldest. */
+const MAX_LOG_BYTES = 512 * 1024;
+
+export type BgStatus = 'running' | 'exited' | 'killed' | 'error';
+
+export interface BgJobView {
+  id: string;
+  command: string;
+  pid: number | null;
+  status: BgStatus;
+  exitCode: number | null;
+  startedAt: number;
+  endedAt: number | null;
+  /** Total bytes ever produced (before any rolling trim). */
+  totalBytes: number;
+}
+
+interface BgJob extends BgJobView {
+  child: ChildProcess | null;
+  log: string;       // combined stdout+stderr in arrival order
+  readOffset: number; // cursor for incremental reads
+  trimmed: number;    // bytes dropped from the front by the rolling cap
+}
+
+class BackgroundManager {
+  private jobs = new Map<string, BgJob>();
+  private seq = 0;
+
+  private append(job: BgJob, text: string): void {
+    job.log += text;
+    job.totalBytes += Buffer.byteLength(text, 'utf8');
+    if (job.log.length > MAX_LOG_BYTES) {
+      const drop = job.log.length - MAX_LOG_BYTES;
+      job.log = job.log.slice(drop);
+      job.trimmed += drop;
+      job.readOffset = Math.max(0, job.readOffset - drop);
+    }
+  }
+
+  /** Start a background command. Returns the job id, or an error string. */
+  start(command: string, opts?: { cwd?: string; env?: Record<string, string> }): { id?: string; error?: string } {
+    const check = preflightCheck(command);
+    if (check) return { error: `[BLOCKED] ${check}` };
+
+    const id = `bg_${(++this.seq).toString(36)}_${Date.now().toString(36)}`;
+    let child: ChildProcess;
+    try {
+      child = spawn(command, {
+        shell: true,
+        cwd: opts?.cwd || process.cwd(),
+        env: { ...process.env, ...(opts?.env || {}) },
+        windowsHide: true,
+      });
+    } catch (e: any) {
+      return { error: `Failed to start background command: ${e.message || e}` };
+    }
+
+    const job: BgJob = {
+      id, command, pid: child.pid ?? null, status: 'running', exitCode: null,
+      startedAt: Date.now(), endedAt: null, totalBytes: 0,
+      child, log: '', readOffset: 0, trimmed: 0,
+    };
+    this.jobs.set(id, job);
+
+    child.stdout?.on('data', (d) => this.append(job, d.toString()));
+    child.stderr?.on('data', (d) => this.append(job, d.toString()));
+    child.on('error', (e) => {
+      job.status = 'error';
+      job.endedAt = Date.now();
+      this.append(job, `\n[spawn error] ${e.message}\n`);
+      log.warn('bg_error', { id, error: e.message });
+    });
+    child.on('exit', (code, signal) => {
+      if (job.status === 'running') job.status = signal ? 'killed' : 'exited';
+      job.exitCode = code;
+      job.endedAt = Date.now();
+      job.child = null;
+    });
+
+    return { id };
+  }
+
+  get(id: string): BgJob | undefined { return this.jobs.get(id); }
+
+  list(): BgJobView[] {
+    return [...this.jobs.values()].map(toView).sort((a, b) => b.startedAt - a.startedAt);
+  }
+
+  /** Read output produced since the last read; advances the cursor. */
+  read(id: string): { ok: boolean; text?: string; status?: BgStatus; exitCode?: number | null; error?: string } {
+    const job = this.jobs.get(id);
+    if (!job) return { ok: false, error: `No background job '${id}'.` };
+    const chunk = job.log.slice(job.readOffset);
+    job.readOffset = job.log.length;
+    return { ok: true, text: chunk, status: job.status, exitCode: job.exitCode };
+  }
+
+  kill(id: string): { ok: boolean; error?: string } {
+    const job = this.jobs.get(id);
+    if (!job) return { ok: false, error: `No background job '${id}'.` };
+    if (job.status !== 'running' || !job.child) return { ok: false, error: `Job '${id}' is not running (${job.status}).` };
+    const pid = job.child.pid;
+    try {
+      if (process.platform === 'win32' && pid) {
+        // child.kill() doesn't reap the cmd.exe process tree on Windows.
+        try { execSync(`taskkill /pid ${pid} /T /F`, { stdio: 'ignore' }); }
+        catch { job.child.kill(); }
+      } else {
+        job.child.kill('SIGTERM');
+      }
+      job.status = 'killed';
+      job.endedAt = Date.now();
+      return { ok: true };
+    } catch (e: any) {
+      return { ok: false, error: `Failed to kill '${id}': ${e.message || e}` };
+    }
+  }
+
+  /** Terminate all running jobs (called on session shutdown). */
+  killAll(): void {
+    for (const job of this.jobs.values()) {
+      if (job.status === 'running') this.kill(job.id);
+    }
+  }
+}
+
+function toView(j: BgJob): BgJobView {
+  return {
+    id: j.id, command: j.command, pid: j.pid, status: j.status,
+    exitCode: j.exitCode, startedAt: j.startedAt, endedAt: j.endedAt, totalBytes: j.totalBytes,
+  };
+}
+
+let _mgr: BackgroundManager | null = null;
+export function getBackgroundManager(): BackgroundManager {
+  if (!_mgr) _mgr = new BackgroundManager();
+  return _mgr;
+}

package/src/core/commands.ts

@@ -313,6 +313,16 @@ export const BUILTIN_COMMANDS: CommandInfo[] = [
     takesArgs: false,
     source: 'builtin',
   },
+  {
+    name: 'agents',
+    aliases: [],
+    description: 'List spawnable subagents',
+    label: '可派生子智能体',
+    category: 'context',
+    hints: [],
+    takesArgs: false,
+    source: 'builtin',
+  },
   {
     name: 'workspace',
     aliases: [],
@@ -428,6 +438,16 @@ export const BUILTIN_COMMANDS: CommandInfo[] = [
     takesArgs: false,
     source: 'builtin',
   },
+  {
+    name: 'perm',
+    aliases: [],
+    description: 'Set permission mode (default|auto|accept|strict|bypass)',
+    label: '权限模式（default/auto/accept/strict/bypass）',
+    category: 'workflow',
+    hints: ['default', 'auto', 'accept', 'strict', 'bypass'],
+    takesArgs: true,
+    source: 'builtin',
+  },
 
   // ── File & Checkpoint ──
   {

package/src/core/diagnostics.ts

@@ -0,0 +1,178 @@
+/**
+ * Code diagnostics — the LSP capability that matters most to an agent: surface
+ * real type/lint errors (with line:col) so the model fixes root causes instead
+ * of guessing.
+ *
+ * Strategy, in order:
+ *   1. TS/JS  → the TypeScript compiler API, resolved from the user's workspace
+ *               node_modules (then sky's own). Real semantic diagnostics, no
+ *               language server to install.
+ *   2. other  → a configured external checker command (config.diagnostics map
+ *               of `ext -> "cmd {file}"`), output parsed for `file:line:col msg`.
+ *
+ * This is intentionally not a full LSP client (hover/goto/rename); it delivers
+ * the diagnostics that close the agent's edit→verify loop on a per-file basis.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { getLogger } from './logger';
+
+const log = getLogger('diagnostics');
+
+export type Severity = 'error' | 'warning' | 'info';
+
+export interface Diagnostic {
+  line: number;      // 1-based
+  column: number;    // 1-based
+  severity: Severity;
+  message: string;
+  code?: string;
+  source?: string;   // 'ts' | external command name
+}
+
+const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']);
+
+/** Resolve the TypeScript module the way an LSP would: workspace first. */
+function loadTypescript(cwd: string): any | null {
+  const bases = [cwd, process.cwd(), __dirname];
+  for (const base of bases) {
+    try {
+      const p = require.resolve('typescript', { paths: [base] });
+      return require(p);
+    } catch { /* try next */ }
+  }
+  try { return require('typescript'); } catch { return null; }
+}
+
+function findNearest(file: string, name: string): string | null {
+  let dir = path.dirname(path.resolve(file));
+  for (let i = 0; i < 40; i++) {
+    const candidate = path.join(dir, name);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/** Semantic + syntactic diagnostics for one TS/JS file via the compiler API. */
+export function getTypeScriptDiagnostics(file: string, cwd: string = process.cwd()): Diagnostic[] | { unavailable: string } {
+  const ts = loadTypescript(cwd);
+  if (!ts) return { unavailable: 'typescript not installed in workspace or sky — cannot type-check.' };
+
+  const abs = path.resolve(file);
+  let options: any = { allowJs: true, checkJs: false, noEmit: true, skipLibCheck: true };
+  let fileNames: string[] = [abs];
+
+  const tsconfig = findNearest(abs, 'tsconfig.json');
+  if (tsconfig) {
+    try {
+      const read = ts.readConfigFile(tsconfig, ts.sys.readFile);
+      const parsed = ts.parseJsonConfigFileContent(read.config || {}, ts.sys, path.dirname(tsconfig));
+      options = { ...parsed.options, noEmit: true };
+      // Keep the project's file set so cross-file types resolve, but ensure our
+      // target is included.
+      fileNames = parsed.fileNames.includes(abs) ? parsed.fileNames : [...parsed.fileNames, abs];
+    } catch (e) {
+      log.warn('tsconfig_parse_failed', { tsconfig, error: String(e) });
+    }
+  }
+
+  let program: any;
+  try {
+    program = ts.createProgram(fileNames, options);
+  } catch (e) {
+    return { unavailable: `failed to build TypeScript program: ${e}` };
+  }
+  const source = program.getSourceFile(abs);
+  if (!source) return { unavailable: `file not part of the TypeScript program: ${abs}` };
+
+  const raw = [
+    ...program.getSyntacticDiagnostics(source),
+    ...program.getSemanticDiagnostics(source),
+  ];
+
+  const out: Diagnostic[] = [];
+  for (const d of raw) {
+    const message = ts.flattenDiagnosticMessageText(d.messageText, '\n');
+    let line = 1, column = 1;
+    if (d.file && typeof d.start === 'number') {
+      const pos = d.file.getLineAndCharacterOfPosition(d.start);
+      line = pos.line + 1;
+      column = pos.character + 1;
+    }
+    const severity: Severity = d.category === 1 ? 'error' : d.category === 0 ? 'warning' : 'info';
+    out.push({ line, column, severity, message, code: d.code ? `TS${d.code}` : undefined, source: 'ts' });
+  }
+  out.sort((a, b) => a.line - b.line || a.column - b.column);
+  return out;
+}
+
+/** Parse generic `path:line:col: message` style compiler/linter output. */
+export function parseDiagnosticOutput(output: string, source: string): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  const re = /^(.*?):(\d+):(\d+):?\s*(error|warning|info)?:?\s*(.*)$/gim;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(output)) !== null) {
+    const sev = (m[4] || 'error').toLowerCase() as Severity;
+    out.push({
+      line: parseInt(m[2], 10) || 1,
+      column: parseInt(m[3], 10) || 1,
+      severity: sev === 'warning' || sev === 'info' ? sev : 'error',
+      message: (m[5] || '').trim(),
+      source,
+    });
+  }
+  return out;
+}
+
+/** Run a configured external checker for a non-TS file. */
+function getExternalDiagnostics(file: string, command: string): Diagnostic[] | { unavailable: string } {
+  const cmd = command.includes('{file}')
+    ? command.replace(/\{file\}/g, JSON.stringify(file))
+    : `${command} ${JSON.stringify(file)}`;
+  let output = '';
+  try {
+    output = execSync(cmd, { encoding: 'utf8', timeout: 60000, stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (e: any) {
+    // Linters exit non-zero when they find problems — that's the normal path.
+    output = `${e.stdout || ''}\n${e.stderr || ''}`;
+  }
+  return parseDiagnosticOutput(output, command.split(/\s+/)[0]);
+}
+
+/**
+ * Get diagnostics for a file. `config.diagnostics` is an optional map of
+ * `ext -> command` for non-TS languages (e.g. { py: "ruff check {file}" }).
+ */
+export function getDiagnostics(file: string, config?: any, cwd: string = process.cwd()): Diagnostic[] | { unavailable: string } {
+  const abs = path.resolve(file);
+  if (!fs.existsSync(abs)) return { unavailable: `file not found: ${abs}` };
+
+  const ext = path.extname(abs).toLowerCase();
+  const map = (config?.diagnostics || {}) as Record<string, string>;
+  const extKey = ext.replace(/^\./, '');
+
+  // Explicit user config wins.
+  if (map[extKey]) return getExternalDiagnostics(abs, map[extKey]);
+  if (TS_EXTS.has(ext)) return getTypeScriptDiagnostics(abs, cwd);
+
+  return { unavailable: `no diagnostics provider for '${ext}'. Configure one in config.yaml diagnostics: { ${extKey || 'ext'}: "<checker> {file}" }` };
+}
+
+export function formatDiagnostics(file: string, diags: Diagnostic[]): string {
+  if (diags.length === 0) return `✓ ${file} — no diagnostics (clean).`;
+  const errs = diags.filter(d => d.severity === 'error').length;
+  const warns = diags.filter(d => d.severity === 'warning').length;
+  const head = `${file} — ${errs} error${errs !== 1 ? 's' : ''}, ${warns} warning${warns !== 1 ? 's' : ''}:`;
+  const lines = diags.slice(0, 100).map(d => {
+    const mark = d.severity === 'error' ? '✗' : d.severity === 'warning' ? '⚠' : 'ℹ';
+    const code = d.code ? ` ${d.code}` : '';
+    return `  ${mark} ${d.line}:${d.column}${code} — ${d.message.replace(/\n/g, ' ')}`;
+  });
+  const more = diags.length > 100 ? `\n  …and ${diags.length - 100} more` : '';
+  return `${head}\n${lines.join('\n')}${more}`;
+}

package/src/core/diff.ts

@@ -0,0 +1,98 @@
+/**
+ * Minimal line-based unified diff for edit previews.
+ *
+ * Edits applied by edit_file are localized (a contiguous region changes), so a
+ * single trimmed hunk — common prefix/suffix removed, the differing middle
+ * shown with a few lines of context — is enough to let the model and the user
+ * see exactly what changed without diffing whole files line-by-line.
+ */
+
+export interface DiffOptions {
+  /** Lines of unchanged context around the change (default 3). */
+  context?: number;
+  /** Optional path shown in the diff header. */
+  path?: string;
+}
+
+export interface DiffStat {
+  added: number;
+  removed: number;
+}
+
+/** Result of rendering a diff: the text plus +/- line counts. */
+export interface DiffResult {
+  text: string;
+  stat: DiffStat;
+}
+
+function commonPrefixLen(a: string[], b: string[]): number {
+  const n = Math.min(a.length, b.length);
+  let i = 0;
+  while (i < n && a[i] === b[i]) i++;
+  return i;
+}
+
+function commonSuffixLen(a: string[], b: string[], skip: number): number {
+  const max = Math.min(a.length, b.length) - skip;
+  let i = 0;
+  while (i < max && a[a.length - 1 - i] === b[b.length - 1 - i]) i++;
+  return i;
+}
+
+/**
+ * Produce a compact unified diff between two strings. Returns the diff text and
+ * a +/- line stat. Identical inputs yield an empty diff (stat 0/0).
+ */
+export function unifiedDiff(oldStr: string, newStr: string, opts: DiffOptions = {}): DiffResult {
+  if (oldStr === newStr) return { text: '', stat: { added: 0, removed: 0 } };
+
+  const context = Math.max(0, opts.context ?? 3);
+  const oldLines = oldStr.split('\n');
+  const newLines = newStr.split('\n');
+
+  let pre = commonPrefixLen(oldLines, newLines);
+  const suf = commonSuffixLen(oldLines, newLines, pre);
+
+  // The changed region (exclusive of the common prefix/suffix).
+  const oldChanged = oldLines.slice(pre, oldLines.length - suf);
+  const newChanged = newLines.slice(pre, newLines.length - suf);
+
+  // Context window bounds.
+  const ctxStart = Math.max(0, pre - context);
+  const oldCtxAfterStart = oldLines.length - suf;
+  const newCtxAfterStart = newLines.length - suf;
+  const oldCtxAfter = oldLines.slice(oldCtxAfterStart, oldCtxAfterStart + context);
+  const leading = oldLines.slice(ctxStart, pre);
+
+  const lines: string[] = [];
+  if (opts.path) lines.push(`--- ${opts.path}`, `+++ ${opts.path}`);
+
+  // Hunk header (1-based line numbers).
+  const oldStart = ctxStart + 1;
+  const oldCount = leading.length + oldChanged.length + oldCtxAfter.length;
+  const newStart = ctxStart + 1;
+  const newCount = leading.length + newChanged.length + oldCtxAfter.length;
+  lines.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+
+  for (const l of leading) lines.push(` ${l}`);
+  for (const l of oldChanged) lines.push(`-${l}`);
+  for (const l of newChanged) lines.push(`+${l}`);
+  for (const l of oldCtxAfter) lines.push(` ${l}`);
+
+  return {
+    text: lines.join('\n'),
+    stat: { added: newChanged.length, removed: oldChanged.length },
+  };
+}
+
+/** Count non-overlapping occurrences of `needle` in `haystack`. */
+export function countOccurrences(haystack: string, needle: string): number {
+  if (!needle) return 0;
+  let count = 0;
+  let idx = haystack.indexOf(needle);
+  while (idx !== -1) {
+    count++;
+    idx = haystack.indexOf(needle, idx + needle.length);
+  }
+  return count;
+}