skyloom 1.16.2 → 1.18.0

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;
+}

package/src/core/envcontext.ts

@@ -0,0 +1,79 @@
+/**
+ * Environment context snapshot — a small, model-visible block describing the
+ * runtime world (working directory, platform, git, Node, date), kept separate
+ * from conversation history. Mirrors Claude Code's <env> block so the agent
+ * grounds itself without having to probe with tools every turn.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+export interface GitInfo {
+  repo: boolean;
+  branch?: string;
+}
+
+/**
+ * Cheap git detection: walk up for a `.git` (handles worktrees, where `.git`
+ * is a file pointing at the real gitdir), then read HEAD for the branch. No
+ * subprocess — just file reads.
+ */
+export function gitInfo(cwd: string = process.cwd()): GitInfo {
+  let dir = path.resolve(cwd);
+  for (let i = 0; i < 40; i++) {
+    const dotGit = path.join(dir, '.git');
+    if (fs.existsSync(dotGit)) {
+      let gitDir = dotGit;
+      try {
+        if (fs.statSync(dotGit).isFile()) {
+          const m = fs.readFileSync(dotGit, 'utf8').match(/gitdir:\s*(.+)/);
+          if (m) gitDir = path.resolve(dir, m[1].trim());
+        }
+      } catch { /* treat as repo without branch */ }
+      try {
+        const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
+        const ref = head.match(/ref:\s*refs\/heads\/(.+)/);
+        return { repo: true, branch: ref ? ref[1] : head.slice(0, 8) };
+      } catch {
+        return { repo: true };
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { repo: false };
+}
+
+/**
+ * Build the environment block. `now` is injectable for deterministic tests.
+ */
+export function buildEnvBlock(opts?: { cwd?: string; lang?: string; now?: Date }): string {
+  const cwd = opts?.cwd || process.cwd();
+  const lang = opts?.lang || 'zh';
+  const now = opts?.now || new Date();
+  const git = gitInfo(cwd);
+  const date = now.toISOString().slice(0, 10);
+  const platform = `${process.platform} ${os.release()}`;
+  const gitLine = git.repo ? (git.branch ? `yes (branch: ${git.branch})` : 'yes') : 'no';
+
+  if (lang === 'en') {
+    return [
+      '## Environment',
+      `- Working directory: ${cwd}`,
+      `- Platform: ${platform}`,
+      `- Node: ${process.version}`,
+      `- Git repo: ${gitLine}`,
+      `- Date: ${date}`,
+    ].join('\n');
+  }
+  return [
+    '## 运行环境',
+    `- 工作目录: ${cwd}`,
+    `- 平台: ${platform}`,
+    `- Node: ${process.version}`,
+    `- Git 仓库: ${gitLine === 'no' ? '否' : gitLine.replace('yes', '是')}`,
+    `- 日期: ${date}`,
+  ].join('\n');
+}

package/src/core/factory.ts

@@ -23,6 +23,7 @@ export class SystemContext {
   workspacePath: string = '';
   mcp: any = null;
   mcpStatus: string[] = [];
+  plugins: any = null;
 
   constructor(opts: {
     config: ReturnType<typeof loadConfig>;
@@ -33,6 +34,7 @@ export class SystemContext {
     workspacePath?: string;
     mcp?: any;
     mcpStatus?: string[];
+    plugins?: any;
   }) {
     this.config = opts.config;
     this.bus = opts.bus;
@@ -42,9 +44,15 @@ export class SystemContext {
     this.workspacePath = opts.workspacePath || '';
     this.mcp = opts.mcp || null;
     this.mcpStatus = opts.mcpStatus || [];
+    this.plugins = opts.plugins || null;
   }
 
   async initAll(): Promise<void> {
+    // Plugin `init` hook — fires once after load, before agents come up.
+    if (this.plugins) {
+      try { await this.plugins.emit('init', { config: this.config }); }
+      catch (e) { log.warn('plugin_init_hook_failed', { error: String(e) }); }
+    }
     if (this.mcp) {
       try {
         this.mcpStatus = await this.mcp.connectAll();
@@ -61,6 +69,11 @@ export class SystemContext {
   }
 
   async closeAll(): Promise<void> {
+    // Terminate any background shell jobs started this session.
+    try {
+      const { getBackgroundManager } = require('./bgproc');
+      getBackgroundManager().killAll();
+    } catch { /* best-effort */ }
     for (const agent of this.agentMap.values()) {
       await agent.close();
     }
@@ -114,10 +127,11 @@ export function createSystemContext(): SystemContext {
     log.warn('skills_not_available', { error: String(e) });
   }
 
-  // Load plugins
+  // Load plugins (ordered hook lifecycle — see plugins/loader)
+  let pluginLoader: any = null;
   try {
     const { PluginLoader } = require('../plugins/loader');
-    const pluginLoader = new PluginLoader(baseToolRegistry);
+    pluginLoader = new PluginLoader(baseToolRegistry, config);
     const pluginConfig = (config as any).plugins;
     const pluginDirs = pluginConfig?.enabled ? (pluginConfig.directories || []) : [];
     pluginLoader.loadFromDirectories(pluginDirs);
@@ -195,6 +209,20 @@ export function createSystemContext(): SystemContext {
         log.warn('delegate_tool_not_available', { agent: name, error: String(e) });
       }
 
+      // Register the spawn_agent tool — isolated-context subagents (Task tool).
+      try {
+        const { createSpawnAgentTool } = require('../tools/spawn');
+        agentRegistry.register(createSpawnAgentTool({
+          config,
+          llm,
+          bus,
+          baseToolRegistry,
+          baseSkillRegistry,
+        }));
+      } catch (e) {
+        log.warn('spawn_tool_not_available', { agent: name, error: String(e) });
+      }
+
       // Register model self-service tools (list_models / set_my_model)
       try {
         const { createModelTools } = require('../tools/model_tool');
@@ -234,6 +262,7 @@ export function createSystemContext(): SystemContext {
     toolRegistry: baseToolRegistry,
     workspacePath,
     mcp: mcpManager,
+    plugins: pluginLoader,
   });
 }
 

package/src/core/patch.ts

@@ -0,0 +1,176 @@
+/**
+ * apply_patch — atomic, multi-file edits for larger refactors.
+ *
+ * Uses exact search/replace blocks (not line-number/context hunks), so it can't
+ * misapply against a drifted file: every SEARCH must match the current file
+ * content exactly and uniquely. The whole patch is validated first; disk is
+ * only touched once every operation is known to apply — so a bad block aborts
+ * the patch without leaving a half-applied tree.
+ *
+ * Format:
+ *   *** Update File: path
+ *   <<<<<<< SEARCH
+ *   exact old text
+ *   =======
+ *   new text
+ *   >>>>>>> REPLACE
+ *   (one or more blocks per file)
+ *
+ *   *** Add File: path
+ *   full file content
+ *
+ *   *** Delete File: path
+ *
+ * An optional `*** Begin Patch` / `*** End Patch` envelope is tolerated.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { countOccurrences, unifiedDiff } from './diff';
+
+export interface PatchBlock { search: string; replace: string; }
+export type PatchOp =
+  | { op: 'update'; path: string; blocks: PatchBlock[] }
+  | { op: 'add'; path: string; content: string }
+  | { op: 'delete'; path: string };
+
+const HDR_UPDATE = /^\*\*\* Update File:\s*(.+?)\s*$/;
+const HDR_ADD = /^\*\*\* Add File:\s*(.+?)\s*$/;
+const HDR_DELETE = /^\*\*\* Delete File:\s*(.+?)\s*$/;
+const MARK_SEARCH = '<<<<<<< SEARCH';
+const MARK_SEP = '=======';
+const MARK_REPLACE = '>>>>>>> REPLACE';
+
+export function parsePatch(text: string): { ops: PatchOp[] } | { error: string } {
+  const lines = text.split(/\r?\n/);
+  const ops: PatchOp[] = [];
+  let i = 0;
+
+  const isHeader = (l: string) => l.startsWith('*** ');
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.startsWith('*** Begin Patch') || line.startsWith('*** End Patch')) { i++; continue; }
+    if (line.trim() === '') { i++; continue; }
+
+    let m: RegExpMatchArray | null;
+    if ((m = line.match(HDR_UPDATE))) {
+      const filePath = m[1];
+      i++;
+      const blocks: PatchBlock[] = [];
+      while (i < lines.length && !isHeader(lines[i])) {
+        if (lines[i].trim() === '') { i++; continue; }
+        if (lines[i] !== MARK_SEARCH) {
+          return { error: `Malformed Update block for '${filePath}': expected '${MARK_SEARCH}', got ${JSON.stringify(lines[i].slice(0, 40))}` };
+        }
+        i++;
+        const search: string[] = [];
+        while (i < lines.length && lines[i] !== MARK_SEP) search.push(lines[i++]);
+        if (i >= lines.length) return { error: `Unterminated SEARCH (missing '${MARK_SEP}') for '${filePath}'` };
+        i++; // consume separator
+        const replace: string[] = [];
+        while (i < lines.length && lines[i] !== MARK_REPLACE) replace.push(lines[i++]);
+        if (i >= lines.length) return { error: `Unterminated REPLACE (missing '${MARK_REPLACE}') for '${filePath}'` };
+        i++; // consume replace marker
+        blocks.push({ search: search.join('\n'), replace: replace.join('\n') });
+      }
+      if (blocks.length === 0) return { error: `Update File '${filePath}' has no SEARCH/REPLACE blocks` };
+      ops.push({ op: 'update', path: filePath, blocks });
+    } else if ((m = line.match(HDR_ADD))) {
+      const filePath = m[1];
+      i++;
+      const content: string[] = [];
+      while (i < lines.length && !isHeader(lines[i])) content.push(lines[i++]);
+      while (content.length && content[content.length - 1] === '') content.pop();
+      ops.push({ op: 'add', path: filePath, content: content.length ? content.join('\n') + '\n' : '' });
+    } else if ((m = line.match(HDR_DELETE))) {
+      ops.push({ op: 'delete', path: m[1] });
+      i++;
+    } else {
+      return { error: `Unexpected line outside any file section: ${JSON.stringify(line.slice(0, 60))}` };
+    }
+  }
+
+  if (ops.length === 0) return { error: 'Patch contains no operations.' };
+  return { ops };
+}
+
+export interface ApplyOptions {
+  cwd?: string;
+  /** Optional workspace-fence check; return a non-null string to abort. */
+  fenceCheck?: (abs: string) => string | null;
+  /** Optional pre-write snapshot hook (for /rewind). */
+  snapshot?: (abs: string) => void;
+}
+
+interface PlannedChange {
+  op: 'update' | 'add' | 'delete';
+  path: string;
+  abs: string;
+  oldContent?: string;
+  newContent?: string;
+}
+
+/**
+ * Validate every operation, then apply them all. Returns a human summary on
+ * success or an `Error: …` string on the first validation failure (no writes).
+ */
+export function applyPatch(text: string, opts: ApplyOptions = {}): string {
+  const cwd = opts.cwd || process.cwd();
+  const parsed = parsePatch(text);
+  if ('error' in parsed) return `Error: ${parsed.error}`;
+
+  const plan: PlannedChange[] = [];
+
+  // ── Validate everything first (no disk mutation) ──
+  for (const op of parsed.ops) {
+    const abs = path.resolve(cwd, op.path);
+    if (opts.fenceCheck) { const f = opts.fenceCheck(abs); if (f) return f; }
+
+    if (op.op === 'update') {
+      if (!fs.existsSync(abs)) return `Error: Update target not found: ${op.path}`;
+      let content: string;
+      try { content = fs.readFileSync(abs, 'utf8'); } catch (e) { return `Error: cannot read ${op.path}: ${e}`; }
+      const orig = content;
+      for (const block of op.blocks) {
+        if (block.search === block.replace) return `Error: a SEARCH/REPLACE block for ${op.path} is a no-op (identical).`;
+        const n = countOccurrences(content, block.search);
+        if (n === 0) return `Error: SEARCH block not found in ${op.path}: ${JSON.stringify(block.search.slice(0, 80))}`;
+        if (n > 1) return `Error: SEARCH block is ambiguous in ${op.path} (appears ${n} times) — add more context to make it unique.`;
+        content = content.replace(block.search, () => block.replace); // literal replacement
+      }
+      plan.push({ op: 'update', path: op.path, abs, oldContent: orig, newContent: content });
+    } else if (op.op === 'add') {
+      if (fs.existsSync(abs)) return `Error: Add target already exists: ${op.path} (use Update File to modify it)`;
+      plan.push({ op: 'add', path: op.path, abs, newContent: op.content });
+    } else {
+      if (!fs.existsSync(abs)) return `Error: Delete target not found: ${op.path}`;
+      plan.push({ op: 'delete', path: op.path, abs });
+    }
+  }
+
+  // ── Apply (validation passed for all ops) ──
+  const summary: string[] = [];
+  for (const p of plan) {
+    try {
+      if (p.op === 'update') {
+        opts.snapshot?.(p.abs);
+        fs.writeFileSync(p.abs, p.newContent!, 'utf8');
+        const d = unifiedDiff(p.oldContent!, p.newContent!, { context: 0 });
+        summary.push(`~ ${p.path} (+${d.stat.added} -${d.stat.removed})`);
+      } else if (p.op === 'add') {
+        fs.mkdirSync(path.dirname(p.abs), { recursive: true });
+        fs.writeFileSync(p.abs, p.newContent!, 'utf8');
+        summary.push(`+ ${p.path} (new)`);
+      } else {
+        opts.snapshot?.(p.abs);
+        fs.unlinkSync(p.abs);
+        summary.push(`- ${p.path} (deleted)`);
+      }
+    } catch (e) {
+      return `Error: patch validated but failed while writing ${p.path}: ${e}\nPartial summary:\n${summary.join('\n')}`;
+    }
+  }
+
+  return `Applied patch — ${plan.length} file${plan.length !== 1 ? 's' : ''}:\n${summary.join('\n')}`;
+}

package/src/core/protocol.ts

@@ -0,0 +1,36 @@
+/**
+ * Engineering protocol — the working discipline injected into every agent's
+ * system prompt so it operates like a senior engineer, not just a code typist.
+ *
+ * Kept as a pure function (no `this`) so it can be unit-tested and evolved in
+ * one place. It deliberately names the project's own capabilities
+ * (code_search / get_diagnostics / run_bash) so the model actually uses the
+ * read→edit→verify loop instead of guessing.
+ */
+
+export function engineeringProtocol(lang: string = 'zh'): string {
+  if (lang === 'en') {
+    return [
+      '## Engineering Standard (work like a senior engineer)',
+      '- Understand before changing: read the target code and its tests/callers (code_search → read_file) before editing. Match the surrounding style, naming, and existing patterns.',
+      '- Reuse first: prefer utilities/libraries already in the project over inventing new ones; check how similar things are done here.',
+      '- Root cause, not symptom: reproduce the failure, find why it happens, fix the cause — never paper over it or hardcode around a test.',
+      '- Minimal, surgical diffs: change only what the task needs. No drive-by reformatting or unrelated edits.',
+      '- Verify your work: after editing code, run get_diagnostics on the changed files and run the project tests/build (run_bash). Do not claim done until it is green; report the real result.',
+      '- Be honest about uncertainty: never fabricate APIs, file paths, or results. If unsure, say so and check.',
+      '- Security & performance: validate inputs, handle errors for real, avoid obvious injection / DoS / performance traps.',
+      'You may read and modify Skyloom\'s own source.',
+    ].join('\n');
+  }
+  return [
+    '## 工程标准(像资深工程师一样工作)',
+    '- 改之前先理解:动手前先读目标代码及其测试/调用方(code_search → read_file),沿用周围的风格、命名与既有模式。',
+    '- 优先复用:优先用项目里已有的工具/库,而不是另造轮子;先看相似功能此处怎么做。',
+    '- 治根因不治症状:先复现失败,定位根本原因再修;绝不糊弄,绝不为了通过测试而硬编码。',
+    '- 最小手术式改动:只改任务所需,不顺手重排格式、不夹带无关修改。',
+    '- 改完必验证:改代码后对改动文件跑 get_diagnostics,并跑项目测试/构建(run_bash);未变绿不算完成,如实汇报真实结果。',
+    '- 诚实面对不确定:绝不编造 API、文件路径或结果;不确定就说明并去核实。',
+    '- 安全与性能:校验输入、做真实的错误处理,避开明显的注入/DoS/性能陷阱。',
+    '你可以阅读和修改 Skyloom 自身源码。',
+  ].join('\n');
+}

package/src/core/sandbox.ts

@@ -44,7 +44,7 @@ function cleanup(dir: string): void {
 /* ═══════════════════════════════════════
    Pre-execution check
    ═══════════════════════════════════════ */
-function preflightCheck(command: string): string | null {
+export function preflightCheck(command: string): string | null {
   if (!command || !command.trim()) return "Empty command";
 
   const lower = command.toLowerCase().trim();