@kingsoftcloud/agentkit-harness-node 0.0.0-stage → 0.0.1

package/src/native/workspace-editing.mjs

@@ -0,0 +1,447 @@
+/**
+ * Read-state reconciliation, edit matching and bounded diff evidence for the
+ * Native Node workspace tools. Filesystem authorization and tool entry points
+ * live in workspace-tools.mjs; this module holds the pure editing logic that
+ * mirrors ksadk.toolsets.workspace_editing.
+ */
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { sha256, TWO_MB } from './workspace-paths.mjs';
+import { findEditMatch, normalizeLineEndings, normalizeReplacementForMatch, preserveQuoteStyle } from '@kingsoftcloud/agentkit-harness-core/edit-matchers';
+/**
+ * Python str.splitlines() boundaries, with \r\n consumed as a single split.
+ * The character class is built from code points at runtime because \u2028 and
+ * \u2029 are line terminators that Node's regex-literal grammar rejects even
+ * as escapes, so a regex literal cannot express the full splitlines boundary
+ * set.
+ */
+const SEPARATOR_CHARS = [0x0a, 0x0d, 0x0b, 0x0c, 0x1c, 0x1d, 0x1e, 0x85, 0x2028, 0x2029];
+const CHAR_CLASS = '[' + SEPARATOR_CHARS.map((c) => String.fromCharCode(c)).join('') + ']';
+const LINE_SPLIT = new RegExp('\\r\\n|' + CHAR_CLASS);
+const LINE_SPLIT_KEEP = new RegExp('(' + '\\r\\n' + '|' + CHAR_CLASS + ')');
+const LINE_SPLIT_END = new RegExp('(?:\\r\\n|' + CHAR_CLASS + ')$');
+
+/** splitlines(keepends=False): drop the trailing empty that follows a final separator. */
+export function splitlines(text) {
+  if (text === '') return [];
+  return splitKeepends(text).map(stripLineEnd);
+}
+
+/** splitlines(keepends=True): keep the separator with the preceding segment. */
+export function splitKeepends(text) {
+  if (text === '') return [];
+  const parts = text.split(LINE_SPLIT_KEEP);
+  const lines = [];
+  for (let i = 0; i < parts.length; i += 2) {
+    const seg = parts[i];
+    const sep = parts[i + 1] ?? '';
+    if (i === parts.length - 1 && seg === '' && sep === '') continue;
+    lines.push(seg + sep);
+  }
+  return lines;
+}
+
+function stripLineEnd(line) {
+  return line.replace(LINE_SPLIT_END, '');
+}
+
+/**
+ * Read a UTF-8 workspace file as raw text, bounded to 2MB. Returns
+ * {text, error}; error is a result-shaped object on failure. Mirrors
+ * _read_workspace_text, including the strict utf-8 rejection.
+ */
+export function readWorkspaceText(target) {
+  let size;
+  try {
+    const info = statSync(target, { bigint: true });
+    if (!info.isFile()) return { text: null, error: { ok: false, error_message: 'workspace file not found' } };
+    size = Number(info.size);
+  } catch (error) {
+    if (error.code === 'ENOENT') return { text: null, error: { ok: false, error_message: 'workspace file not found' } };
+    return { text: null, error: { ok: false, error_message: 'workspace file not found' } };
+  }
+  if (size > TWO_MB) return { text: null, error: { ok: false, error_message: 'file is larger than 2MB' } };
+  let payload;
+  try {
+    const fd = openSync(target, 'r');
+    try {
+      const buf = Buffer.alloc(TWO_MB + 1);
+      const n = readSync(fd, buf, 0, TWO_MB + 1, null);
+      payload = buf.subarray(0, n);
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return { text: null, error: { ok: false, error_message: 'workspace file read failed' } };
+  }
+  if (payload.length > TWO_MB) return { text: null, error: { ok: false, error_message: 'file is larger than 2MB' } };
+  let text;
+  try {
+    // Python's payload.decode('utf-8') is strict and keeps a BOM; reproduce
+    // that with a fatal TextDecoder that does not strip the BOM.
+    text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(payload);
+  } catch {
+    return { text: null, error: { ok: false, error_message: 'file is not utf-8 text' } };
+  }
+  return { text, error: null };
+}
+
+/**
+ * Validate that an observed read state still matches the file on disk. Returns
+ * null when valid, or a result-shaped error. Mirrors _validate_read_state:
+ * a missing/partial-omitted state is file_not_read; a changed mtime, size or
+ * content digest is file_modified_since_read.
+ */
+export function validateReadState(target, relative, { state, content = null }) {
+  if (!state || state.canonicalPath !== target || !state.contentSha256) {
+    return {
+      ok: false,
+      path: relative,
+      error_type: 'file_not_read',
+      error_message: 'file must be read before editing',
+      suggested_action: `Call read_workspace_file(path=${quote(relative)}) before editing.`,
+    };
+  }
+  let stat = null;
+  try {
+    stat = statSync(target, { bigint: true });
+  } catch { /* missing below */ }
+  if (
+    stat === null
+    || stat.mtimeNs !== state.mtimeNs
+    || Number(stat.size) !== state.sizeBytes
+    || (content !== null && sha256(Buffer.from(content, 'utf-8')) !== state.contentSha256)
+  ) {
+    return {
+      ok: false,
+      path: relative,
+      error_type: 'file_modified_since_read',
+      error_message: 'workspace file changed since last read',
+      suggested_action: `Re-read the file with read_workspace_file(path=${quote(relative)}) and retry.`,
+    };
+  }
+  return null;
+}
+
+export function validateSingleEditRequest(oldText, relative) {
+  if (!String(oldText ?? '')) {
+    return {
+      ok: false,
+      path: relative,
+      error_type: 'missing_old_text',
+      error_message: 'old_text is required',
+    };
+  }
+  return null;
+}
+
+const QUOTE_MAP = { '“': '"', '”': '"', '„': '"', '‘': "'", '’': "'", '‚': "'" };
+const SMART_TO_ASCII = { '"': '“', "'": '‘' };
+
+export function normalizeQuotes(value) {
+  return value.replace(/[“”„‘’‚]/g, (ch) => QUOTE_MAP[ch]);
+}
+
+/**
+ * Find the actual occurrence of old in text, tolerating smart/straight quote
+ * substitution. Returns {actual, usedQuoteNormalization}. Mirrors
+ * _find_actual_string: exact match first, then normalized, then sliced.
+ */
+export function findActualString(text, old) {
+  if (text.includes(old)) return { actual: old, usedQuoteNormalization: false };
+  const normalizedOld = normalizeQuotes(old);
+  const candidates = new Set([normalizedOld, old.replace(/["']/g, (ch) => SMART_TO_ASCII[ch] ?? ch)]);
+  for (const candidate of candidates) {
+    if (candidate && text.includes(candidate)) return { actual: candidate, usedQuoteNormalization: true };
+  }
+  const normalizedText = normalizeQuotes(text);
+  const index = normalizedText.indexOf(normalizedOld);
+  if (index < 0) return { actual: null, usedQuoteNormalization: false };
+  return { actual: text.slice(index, index + old.length), usedQuoteNormalization: true };
+}
+
+export function matchPreviews(text, needle, limit = 20) {
+  if (!needle) return [];
+  const matches = [];
+  const lines = splitlines(text);
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(needle)) {
+      matches.push({ line: i + 1, text: lines[i].trim(), snippet: lines[i] });
+      if (matches.length >= limit) break;
+    }
+  }
+  return matches;
+}
+
+export function nearbyCandidates(text, old, limit = 5) {
+  const oldNorm = normalizeQuotes(old).trim();
+  const candidates = [];
+  const lines = splitlines(text);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNorm = normalizeQuotes(line).trim();
+    const ratio = similarityRatio(oldNorm, lineNorm);
+    const prefix = oldNorm.slice(0, Math.max(1, Math.min(4, oldNorm.length)));
+    if (oldNorm && (lineNorm.includes(prefix) || ratio > 0.45)) {
+      candidates.push({ line: i + 1, text: line.trim(), snippet: line, score: Math.round(ratio * 1000) / 1000 });
+    }
+  }
+  candidates.sort((a, b) => (b.score - a.score) || (a.line - b.line));
+  return candidates.slice(0, limit);
+}
+
+/** difflib.SequenceMatcher.ratio() approximation: 2*M/(len(a)+len(b)). */
+function similarityRatio(a, b) {
+  if (!a && !b) return 1;
+  if (!a || !b) return 0;
+  const matches = lcsLength(a, b);
+  return (2 * matches) / (a.length + b.length);
+}
+
+function lcsLength(a, b) {
+  if (a.length < b.length) [a, b] = [b, a];
+  const m = a.length, n = b.length;
+  let prev = new Array(n + 1).fill(0);
+  let curr = new Array(n + 1).fill(0);
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      curr[j] = a[i - 1] === b[j - 1] ? prev[j - 1] + 1 : Math.max(prev[j], curr[j - 1]);
+    }
+    [prev, curr] = [curr, prev];
+    curr.fill(0);
+  }
+  return prev[n];
+}
+
+/**
+ * Apply one exact-text edit. Matches LF/CRLF snippets against the file's
+ * prevailing line ending without converting unrelated bytes. Mirrors
+ * _apply_single_edit, including expected_replacements/replace_all semantics.
+ */
+export function applySingleEdit(text, oldText, newText, { expectedReplacements = 1, replaceAll = false, relative }) {
+  const requestError = validateSingleEditRequest(oldText, relative);
+  if (requestError) return requestError;
+  const ending = text.includes('\r\n') ? '\r\n' : '\n';
+  const old = String(oldText).replace(/\r\n/g, '\n').replace(/\n/g, ending);
+  const replacement = String(newText ?? '').replace(/\r\n/g, '\n').replace(/\n/g, ending);
+  const expected = Math.max(1, Number(expectedReplacements || 1));
+  const { actual, usedQuoteNormalization } = findActualString(text, old);
+  const matches = actual ? matchPreviews(text, actual) : [];
+  const occurrences = actual ? countOccurrences(text, actual) : 0;
+  if (occurrences === 0) {
+    return {
+      ok: false,
+      path: relative,
+      error_type: 'snippet_not_found',
+      error_message: 'old_text was not found in the workspace file',
+      occurrences: 0,
+      nearby_candidates: nearbyCandidates(text, old),
+      suggested_action: 'Use one nearby candidate as old_text, or call read_workspace_file with line numbers and retry.',
+    };
+  }
+  if (actual === null) {
+    return { ok: false, path: relative, error_type: 'snippet_not_found', error_message: 'old_text was not found in the workspace file' };
+  }
+  if (!replaceAll && occurrences !== expected) {
+    return {
+      ok: false,
+      path: relative,
+      error_type: 'ambiguous_edit',
+      error_message: `old_text matched ${occurrences} occurrences, expected ${expected}`,
+      occurrences,
+      expected_replacements: expected,
+      matches,
+      suggested_action: 'Provide a larger unique old_text snippet, set expected_replacements, or use replace_all=true.',
+    };
+  }
+  const replacements = replaceAll ? occurrences : expected;
+  return {
+    ok: true,
+    updated: replaceFirst(text, actual, replacement, replacements),
+    replacements,
+    used_quote_normalization: usedQuoteNormalization,
+    matches,
+  };
+}
+
+function countOccurrences(text, needle) {
+  if (!needle) return 0;
+  let count = 0;
+  let from = 0;
+  while ((from = text.indexOf(needle, from)) !== -1) { count++; from += needle.length; }
+  return count;
+}
+
+/** Pure reference matching; called in the bounded worker, never with file authority. */
+export function applyZcodeEdit(text, oldText, newText, { expectedReplacements = 1, replaceAll = false, relative }) {
+  const invalid = validateSingleEditRequest(oldText, relative);
+  if (invalid) return invalid;
+  if (oldText === newText) return { ok: false, path: relative, error_type: 'no_change', error_message: 'old_text and new_text are identical' };
+  const content = normalizeLineEndings(text), search = normalizeLineEndings(oldText);
+  const match = findEditMatch({ content, search, replaceAll });
+  if (match.status === 'not_found') return { ok: false, path: relative, error_type: 'snippet_not_found',
+    error_message: 'old_text was not found in the workspace file', occurrences: 0,
+    nearby_candidates: nearbyCandidates(content, search), suggested_action: 'Read the current file and provide a unique old_text snippet.' };
+  if (match.status === 'ambiguous') return { ok: false, path: relative, error_type: 'ambiguous_edit',
+    error_message: 'Normalized old_text matches different file fragments. Provide a larger unique snippet.',
+    occurrences: match.candidateCount, match_strategy: match.strategy, suggested_action: 'Read the current file and use a unique exact snippet.' };
+  const occurrences = countOccurrences(content, match.actualString), expected = Math.max(1, Number(expectedReplacements || 1));
+  if (!replaceAll && occurrences !== expected) return { ok: false, path: relative, error_type: 'ambiguous_edit',
+    error_message: `old_text matched ${occurrences} occurrences, expected ${expected}`, occurrences,
+    expected_replacements: expected, matches: matchPreviews(content, match.actualString), match_strategy: match.strategy,
+    suggested_action: 'Provide a larger unique snippet or use replace_all=true.' };
+  const replacement = preserveQuoteStyle(search, match.actualString,
+    normalizeReplacementForMatch(match.strategy, normalizeLineEndings(newText)));
+  const ending = text.includes('\r\n') ? '\r\n' : '\n';
+  // Match normalized LF across the original bytes, preserving all untouched
+  // line endings. A callback keeps replacement $ sequences literal.
+  const actualSearch = replacement === '' && !match.actualString.endsWith('\n') && content.includes(`${match.actualString}\n`)
+    ? `${match.actualString}\n` : match.actualString;
+  const pattern = actualSearch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').split('\n').join('\\r?\\n');
+  let remaining = replaceAll ? occurrences : expected, replacements = 0;
+  const updated = text.replace(new RegExp(pattern, 'g'), actual => {
+    if (remaining-- <= 0) return actual;
+    replacements++; return replacement.replaceAll('\n', ending);
+  });
+  return { ok: true, updated, replacements,
+    used_quote_normalization: match.strategy === 'quote_normalized', match_strategy: match.strategy,
+    match_candidate_count: match.candidateCount, matches: matchPreviews(content, match.actualString) };
+}
+
+function replaceFirst(text, needle, replacement, count) {
+  let result = '';
+  let from = 0;
+  let replaced = 0;
+  while (replaced < count) {
+    const idx = text.indexOf(needle, from);
+    if (idx === -1) break;
+    result += text.slice(from, idx) + replacement;
+    from = idx + needle.length;
+    replaced++;
+  }
+  result += text.slice(from);
+  return result;
+}
+
+/** Locate the changed middle: shared prefix and suffix line runs. */
+export function changedMiddle(before, after) {
+  const oldLines = splitKeepends(before);
+  const newLines = splitKeepends(after);
+  let first = 0;
+  while (first < Math.min(oldLines.length, newLines.length) && oldLines[first] === newLines[first]) first++;
+  let endOld = oldLines.length, endNew = newLines.length;
+  while (endOld > first && endNew > first && oldLines[endOld - 1] === newLines[endNew - 1]) { endOld--; endNew--; }
+  return { oldLines, newLines, first, endOld, endNew };
+}
+
+/** LCS-based opcodes over two line arrays: equal/replace/insert/delete. */
+export function lineDiffOpcodes(a, b) {
+  const n = a.length, m = b.length;
+  const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0, j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      const start = i;
+      while (i < n && j < m && a[i] === b[j]) { i++; j++; }
+      ops.push({ tag: 'equal', aStart: start, aEnd: i, bStart: start, bEnd: j });
+    } else {
+      const aS = i, bS = j;
+      while (i < n && j < m && a[i] !== b[j]) {
+        if (dp[i + 1][j] >= dp[i][j + 1]) i++; else j++;
+      }
+      if (i > aS && j > bS) ops.push({ tag: 'replace', aStart: aS, aEnd: i, bStart: bS, bEnd: j });
+      else if (i > aS) ops.push({ tag: 'delete', aStart: aS, aEnd: i, bStart: bS, bEnd: bS });
+      else ops.push({ tag: 'insert', aStart: aS, aEnd: aS, bStart: bS, bEnd: j });
+    }
+  }
+  if (i < n) ops.push({ tag: 'delete', aStart: i, aEnd: n, bStart: m, bEnd: m });
+  if (j < m) ops.push({ tag: 'insert', aStart: n, aEnd: n, bStart: j, bEnd: m });
+  return ops;
+}
+
+export function changeCounts(before, after) {
+  const { oldLines, newLines, first, endOld, endNew } = changedMiddle(before, after);
+  if ((endOld - first) * (endNew - first) > 1_000_000) {
+    return { diff_additions: endNew - first, diff_deletions: endOld - first };
+  }
+  const ops = lineDiffOpcodes(oldLines.slice(first, endOld), newLines.slice(first, endNew));
+  let additions = 0, deletions = 0;
+  for (const op of ops) {
+    if (op.tag === 'equal') continue;
+    additions += op.bEnd - op.bStart;
+    deletions += op.aEnd - op.aStart;
+  }
+  return { diff_additions: additions, diff_deletions: deletions };
+}
+
+/** Unified-diff hunk header range, matching difflib._format_range_unified. */
+function formatRange(start, length) {
+  const beginning = start + 1;
+  if (length === 1) return `${beginning}`;
+  if (length === 0) return `${beginning - 1},0`;
+  return `${beginning},${length}`;
+}
+
+export function buildDiff(relative, before, after) {
+  const { oldLines, newLines, first, endOld, endNew } = changedMiddle(before, after);
+  if (first === endOld && first === endNew) return '';
+  if ((endOld - first) * (endNew - first) > 1_000_000) {
+    return bulkMiddleHunk(relative, oldLines, newLines, first, endOld, endNew);
+  }
+  return singleHunk(relative, oldLines, newLines, first, endOld, endNew, 3);
+}
+
+/** Fast path for a huge changed middle: emit the whole span as one hunk. */
+function bulkMiddleHunk(relative, oldLines, newLines, first, endOld, endNew) {
+  let diff = `--- ${relative} before\n+++ ${relative} after\n`;
+  diff += `@@ -${formatRange(first, endOld - first)} +${formatRange(first, endNew - first)} @@\n`;
+  for (let k = first; k < endOld; k++) diff += '-' + oldLines[k];
+  for (let k = first; k < endNew; k++) diff += '+' + newLines[k];
+  return diff;
+}
+
+/** One unified-diff hunk over the changed middle with optional context lines. */
+function singleHunk(relative, oldLines, newLines, first, endOld, endNew, context) {
+  const ops = lineDiffOpcodes(oldLines.slice(first, endOld), newLines.slice(first, endNew));
+  const beforeStart = Math.max(0, first - context);
+  const afterEnd = Math.min(oldLines.length, endOld + context);
+  const body = [];
+  for (let k = beforeStart; k < first; k++) body.push(' ' + oldLines[k]);
+  for (const op of ops) {
+    if (op.tag === 'equal') {
+      for (let k = op.aStart; k < op.aEnd; k++) body.push(' ' + oldLines[first + k]);
+    } else {
+      if (op.tag === 'replace' || op.tag === 'delete') {
+        for (let k = op.aStart; k < op.aEnd; k++) body.push('-' + oldLines[first + k]);
+      }
+      if (op.tag === 'replace' || op.tag === 'insert') {
+        for (let k = op.bStart; k < op.bEnd; k++) body.push('+' + newLines[first + k]);
+      }
+    }
+  }
+  for (let k = endOld; k < afterEnd; k++) body.push(' ' + oldLines[k]);
+  const aStart = beforeStart;
+  const aLen = afterEnd - beforeStart;
+  const bStart = beforeStart; // the context prefix is equal in both files
+  const bAfterEnd = Math.min(newLines.length, endNew + context);
+  const bLen = bAfterEnd - beforeStart;
+  let diff = `--- ${relative} before\n+++ ${relative} after\n`;
+  diff += `@@ -${formatRange(aStart, aLen)} +${formatRange(bStart, bLen)} @@\n`;
+  diff += body.join('');
+  return diff;
+}
+
+export function diffLineCount(diff) {
+  let count = 0;
+  for (let i = 0; i < diff.length; i++) if (diff[i] === '\n') count++;
+  return count;
+}
+
+function quote(value) {
+  return `'${value}'`;
+}

package/src/native/workspace-image.mjs

@@ -0,0 +1,72 @@
+import { closeSync, constants, fstatSync, openSync, readSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+const MAX_PIXELS = 40_000_000;
+const fail = code => { throw Object.assign(Error(code), { code }); };
+function imageInfo(data) {
+  if (data.length >= 24 && data.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+    return { mime_type: 'image/png', width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
+  if (data.length >= 10 && ['GIF87a', 'GIF89a'].includes(data.subarray(0, 6).toString()))
+    return { mime_type: 'image/gif', width: data.readUInt16LE(6), height: data.readUInt16LE(8) };
+  if (data.length >= 30 && data.toString('ascii', 0, 4) === 'RIFF' && data.toString('ascii', 8, 12) === 'WEBP') {
+    const kind = data.toString('ascii', 12, 16);
+    if (kind === 'VP8X') return { mime_type: 'image/webp', width: 1 + data.readUIntLE(24, 3), height: 1 + data.readUIntLE(27, 3) };
+    if (kind === 'VP8 ' && data.subarray(23, 26).equals(Buffer.from([157, 1, 42])))
+      return { mime_type: 'image/webp', width: data.readUInt16LE(26) & 0x3fff, height: data.readUInt16LE(28) & 0x3fff };
+    if (kind === 'VP8L' && data[20] === 0x2f) return { mime_type: 'image/webp',
+      width: 1 + ((data[21] | data[22] << 8) & 0x3fff), height: 1 + ((data[22] >> 6 | data[23] << 2 | data[24] << 10) & 0x3fff) };
+  }
+  if (data[0] === 255 && data[1] === 216) {
+    for (let i = 2; i + 4 <= data.length;) {
+      if (data[i++] !== 255) return null;
+      while (data[i] === 255) i++;
+      const marker = data[i++];
+      if (marker === 0xda || marker === 0xd9) break;
+      if (marker === 0x01 || marker >= 0xd0 && marker <= 0xd7) continue;
+      if (i + 2 > data.length) break;
+      const length = data.readUInt16BE(i);
+      if (length < 2 || i + length > data.length) break;
+      if ([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf].includes(marker) && length >= 7)
+        return { mime_type: 'image/jpeg', height: data.readUInt16BE(i + 3), width: data.readUInt16BE(i + 5) };
+      i += length;
+    }
+  }
+  return null;
+}
+
+/** Read a bounded, stable image observation through the existing workspace authorization. No URL fetching or execution. */
+export function readBoundedWorkspaceImage(target, path, checkCurrent) {
+  const fd = openSync(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    checkCurrent();
+    const before = fstatSync(fd, { bigint: true });
+    if (!before.isFile()) fail('workspace_image_not_regular');
+    const header = Buffer.alloc(32), headerSize = readSync(fd, header, 0, 32, 0), bytes = header.subarray(0, headerSize);
+    const candidate = /\.(png|jpe?g|gif|webp)$/i.test(path)
+      || bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+      || bytes[0] === 255 && bytes[1] === 216
+      || ['GIF87a', 'GIF89a'].includes(bytes.subarray(0, 6).toString())
+      || bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP';
+    if (!candidate) return null;
+    if (before.size > BigInt(MAX_IMAGE_BYTES)) fail('workspace_image_too_large');
+    const buffer = Buffer.alloc(Number(before.size) + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const count = readSync(fd, buffer, length, buffer.length - length, length);
+      if (!count) break;
+      length += count;
+    }
+    checkCurrent();
+    const after = fstatSync(fd, { bigint: true }), current = statSync(target, { bigint: true });
+    if (before.dev !== current.dev || before.ino !== current.ino || before.size !== after.size
+      || before.mtimeNs !== after.mtimeNs || BigInt(length) !== before.size) fail('workspace_image_changed');
+    const data = buffer.subarray(0, length), info = imageInfo(data);
+    if (!info || info.width < 1 || info.height < 1) fail('workspace_image_invalid');
+    if (info.width * info.height > MAX_PIXELS) fail('workspace_image_dimensions_exceeded');
+    const content = { ok: true, path, observation_kind: 'image', ...info, size_bytes: length,
+      sha256: createHash('sha256').update(data).digest('hex') };
+    return { content, context: { content: JSON.stringify(content), media: [{ type: 'image_url',
+      image_url: { url: `data:${info.mime_type};base64,${data.toString('base64')}` } }] } };
+  } finally { closeSync(fd); }
+}

package/src/native/workspace-instructions.mjs

@@ -0,0 +1,107 @@
+import { constants, realpathSync } from 'node:fs';
+import { open, realpath, stat } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import { canonical, invariant, INSTRUCTION_SCOPES, validateInstructionScopes } from '@kingsoftcloud/agentkit-harness-core';
+import { validateNativeWorkspaceContext } from './workspace-context.mjs';
+import { isInside, realpathExisting } from './workspace-paths.mjs';
+
+const CONTRACT = 'agentkit.native-instruction-files/v1';
+const CANDIDATES = ['AGENTS.md', 'CLAUDE.md', 'AGENTS.local.md', 'CLAUDE.local.md'];
+const MAX_FILE_BYTES = 65536, MAX_TOTAL_BYTES = 98304;
+const hash = value => createHash('sha256').update(value).digest('hex');
+const missing = error => ['ENOENT', 'ENOTDIR'].includes(error.code);
+const sameFile = (a, b) => ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs'].every(key => a[key] === b[key]);
+
+/** Stable bounded reads, using the physical file identity both before and after
+ * open. A concurrent replacement causes a retryable source failure, not stale
+ * guidance or a partially read instruction file. */
+async function readFile(root, path, signal) {
+  signal.throwIfAborted();
+  let physical, before, handle;
+  try {
+    physical = await realpath(path);
+    invariant(isInside(physical, root), 'workspace_instruction_path_escape');
+    before = await stat(physical, { bigint: true });
+    if (!before.isFile()) return null;
+    invariant(before.size <= BigInt(MAX_FILE_BYTES), 'workspace_instruction_file_too_large');
+    handle = await open(physical, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    invariant(sameFile(before, await handle.stat({ bigint: true })) && await realpath(path) === physical,
+      'workspace_instruction_file_changed');
+    const parts = []; let bytes = 0;
+    for await (const part of handle.createReadStream({ autoClose: false, signal, end: MAX_FILE_BYTES })) {
+      bytes += part.length; invariant(bytes <= MAX_FILE_BYTES, 'workspace_instruction_file_too_large'); parts.push(part);
+    }
+    signal.throwIfAborted();
+    invariant(sameFile(before, await handle.stat({ bigint: true })) && await realpath(path) === physical,
+      'workspace_instruction_file_changed');
+    return Buffer.concat(parts).toString('utf8');
+  } catch (error) {
+    // Absence is current state. Once opened, disappearance is a changed read.
+    if (!handle && missing(error)) return null;
+    throw error;
+  } finally { await handle?.close(); }
+}
+
+/** Node-owned live source. Only discovery directories are durable; file bodies
+ * and deletion state never depend on a summary or a process-local cache. */
+export function createNativeWorkspaceInstructions(binding) {
+  validateNativeWorkspaceContext(binding);
+  invariant(binding.instructionSource?.contract === CONTRACT, 'workspace_instruction_source_unbound');
+  const root = binding.workspaceRoot, roots = structuredClone(binding.instructionSource.globalRoots);
+  const source = Object.freeze({ contract: 'agentkit.native-context-source/v1', sourceId: 'native.workspace-instructions',
+    bindingDigest: hash(canonical({ contract: CONTRACT, root, roots, candidates: CANDIDATES, MAX_FILE_BYTES, MAX_TOTAL_BYTES })),
+    instructionPolicy: 'current-files/v1', priority: 1000, required: true, timeoutMs: 5000, maxTokens: 32768, maxBytes: 131072 });
+  const initialScopes = () => ({ contract: INSTRUCTION_SCOPES, sourceId: source.sourceId,
+    bindingDigest: source.bindingDigest, directories: [''] });
+  const scopesOf = state => state === undefined ? initialScopes() : validateInstructionScopes(state, { contextSources: [source] });
+  return {
+    source,
+    workspaceRoot: root,
+    async scopes(previous, touches, signal) {
+      const result = scopesOf(previous), directories = new Set(result.directories);
+      directories.add('');
+      invariant(realpathSync(root) === root, 'workspace_instruction_root_changed');
+      for (const touch of touches) {
+        signal.throwIfAborted();
+        const target = realpathExisting(resolve(root, touch));
+        invariant(isInside(target, root), 'workspace_instruction_path_escape');
+        let directory = dirname(target);
+        try { if ((await stat(target)).isDirectory()) directory = target; }
+        catch (error) { if (!missing(error)) throw error; }
+        while (isInside(directory, root)) {
+          directories.add(relative(root, directory).split(sep).join('/'));
+          if (directory === root) break;
+          directory = dirname(directory);
+        }
+      }
+      result.directories = [...directories].sort((a, b) => a.split('/').length - b.split('/').length || a.localeCompare(b));
+      return validateInstructionScopes(result, { contextSources: [source] });
+    },
+    async readSource({ source: requested, snapshot, signal }) {
+      invariant(canonical(requested) === canonical(source), 'workspace_instruction_source_changed');
+      invariant(await realpath(root) === root, 'workspace_instruction_root_changed');
+      const scopes = scopesOf(snapshot.context.instructionScopes), files = [], dedup = new Set(); let bytes = 0;
+      async function add(directory, path, display, scope, group) {
+        const content = await readFile(directory, path, signal);
+        if (content === null || !content.trim()) return;
+        const key = group + ':' + hash(content.trim());
+        if (dedup.has(key)) return;
+        dedup.add(key); bytes += Buffer.byteLength(content);
+        invariant(bytes <= MAX_TOTAL_BYTES && files.length < 256, 'workspace_instruction_source_too_large');
+        files.push({ path: display, scope, sha256: hash(content), content });
+      }
+      for (const [index, globalRoot] of roots.entries()) {
+        // A newly introduced symlink cannot widen a frozen global root.
+        invariant(realpathExisting(globalRoot) === globalRoot, 'workspace_instruction_root_changed');
+        await add(globalRoot, join(globalRoot, 'AGENTS.md'), `global:${index}/AGENTS.md`, 'user-global', 'user-global');
+      }
+      for (const directory of scopes.directories) for (const name of CANDIDATES) {
+        const path = directory ? `${directory}/${name}` : name;
+        await add(root, join(root, path), path, directory || '.', directory);
+      }
+      // Empty files is significant: it retires all previously active versions.
+      return { items: [{ contract: CONTRACT, workspaceRoot: root, directories: scopes.directories, files }] };
+    },
+  };
+}