@agent-sh/harness-read 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avi Fenesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @agent-sh/harness-read
+
+Safe, bounded, line-numbered file reading with pagination, binary refusal, and fuzzy-sibling NOT_FOUND.
+
+Part of the [`@agent-sh/harness-*`](https://github.com/avifenesh/tools) monorepo — see the top-level README for architectural context and the full tool surface.
+
+## Install
+
+```sh
+npm install @agent-sh/harness-read
+```
+
+Requires Node ≥ 20.
+
+## Usage
+
+```ts
+import { read } from "@agent-sh/harness-read";
+
+const r = await read(
+  { path: "src/index.ts", offset: 1, limit: 200 },
+  { cwd: process.cwd(), permissions: { roots: [process.cwd()], sensitivePatterns: [] } },
+);
+
+if (r.kind === "text") console.log(r.output);
+```
+
+## Contract
+
+The full contract — input shape, output discriminated-union, error codes, permission model, and acceptance tests — lives in [`agent-knowledge/design/read.md`](https://github.com/avifenesh/tools/blob/main/agent-knowledge/design/read.md). Changes to this package must stay in sync with that spec.
+
+## License
+
+MIT © Avi Fenesh

package/dist/index.cjs

@@ -0,0 +1,590 @@
+'use strict';
+
+var buffer = require('buffer');
+var crypto = require('crypto');
+var path3 = require('path');
+var harnessCore = require('@agent-sh/harness-core');
+var v = require('valibot');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var path3__default = /*#__PURE__*/_interopDefault(path3);
+var v__namespace = /*#__PURE__*/_interopNamespace(v);
+
+// src/read.ts
+
+// src/constants.ts
+var DEFAULT_LIMIT = 2e3;
+var MAX_LINE_LENGTH = 2e3;
+var MAX_LINE_SUFFIX = `... (line truncated to ${MAX_LINE_LENGTH} chars)`;
+var MAX_BYTES = 50 * 1024;
+var MAX_BYTES_LABEL = `${MAX_BYTES / 1024} KB`;
+var MAX_FILE_SIZE = 5 * 1024 * 1024;
+var BINARY_SAMPLE_BYTES = 4096;
+var FUZZY_SUGGESTION_LIMIT = 3;
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".zip",
+  ".tar",
+  ".gz",
+  ".exe",
+  ".dll",
+  ".so",
+  ".class",
+  ".jar",
+  ".war",
+  ".7z",
+  ".doc",
+  ".docx",
+  ".xls",
+  ".xlsx",
+  ".ppt",
+  ".pptx",
+  ".odt",
+  ".ods",
+  ".odp",
+  ".bin",
+  ".dat",
+  ".obj",
+  ".o",
+  ".a",
+  ".lib",
+  ".wasm",
+  ".pyc",
+  ".pyo"
+]);
+
+// src/binary.ts
+function isBinaryByExtension(filepath) {
+  return BINARY_EXTENSIONS.has(path3__default.default.extname(filepath).toLowerCase());
+}
+function isBinaryByContent(sample) {
+  if (sample.length === 0) return false;
+  let nonPrintable = 0;
+  for (let i = 0; i < sample.length; i++) {
+    const b = sample[i];
+    if (b === 0) return true;
+    if (b < 9 || b > 13 && b < 32) nonPrintable++;
+  }
+  return nonPrintable / sample.length > 0.3;
+}
+function isBinary(filepath, sample) {
+  return isBinaryByExtension(filepath) || isBinaryByContent(sample);
+}
+function isImageMime(mime) {
+  if (!mime.startsWith("image/")) return false;
+  if (mime === "image/svg+xml") return false;
+  return true;
+}
+function isPdfMime(mime) {
+  return mime === "application/pdf";
+}
+
+// src/format.ts
+function formatText(params) {
+  const { path: path4, offset, lines, totalLines, more, byteCap } = params;
+  const header = `<path>${path4}</path>
+<type>file</type>
+<content>`;
+  if (lines.length === 0 && totalLines === 0) {
+    return `${header}
+(File exists but is empty)
+</content>`;
+  }
+  const body = lines.map((line, i) => `${offset + i}: ${line}`).join("\n");
+  const last = offset + lines.length - 1;
+  const next = last + 1;
+  let hint;
+  if (byteCap) {
+    const pct = totalLines > 0 ? Math.round(last / totalLines * 100) : 0;
+    const remaining = Math.max(totalLines - last, 0);
+    hint = `(Output capped at ${MAX_BYTES_LABEL}. Showing lines ${offset}-${last} of ${totalLines} \xB7 ${pct}% covered \xB7 ${remaining} lines remaining. Next offset: ${next}.)`;
+  } else if (more) {
+    const pct = Math.round(last / totalLines * 100);
+    const remaining = Math.max(totalLines - last, 0);
+    hint = `(Showing lines ${offset}-${last} of ${totalLines} \xB7 ${pct}% covered \xB7 ${remaining} lines remaining. Next offset: ${next}.)`;
+  } else {
+    hint = `(End of file \xB7 ${totalLines} lines total)`;
+  }
+  return `${header}
+${body}
+
+${hint}
+</content>`;
+}
+function formatDirectory(params) {
+  const { path: path4, entries, offset, totalEntries, more } = params;
+  const header = `<path>${path4}</path>
+<type>directory</type>
+<entries>`;
+  const body = entries.join("\n");
+  const last = offset + entries.length - 1;
+  const next = last + 1;
+  const remaining = Math.max(totalEntries - last, 0);
+  const hint = more ? `(Showing ${entries.length} of ${totalEntries} entries \xB7 ${remaining} remaining. Next offset: ${next}.)` : `(${totalEntries} entries)`;
+  return `${header}
+${body}
+
+${hint}
+</entries>`;
+}
+function formatAttachment(kind) {
+  return `${kind} read successfully`;
+}
+async function streamLines(ops, path4, opts) {
+  const maxBytes = opts.maxBytes ?? MAX_BYTES;
+  const maxLineLen = opts.maxLineLength ?? MAX_LINE_LENGTH;
+  const start = opts.offset - 1;
+  const out = [];
+  let bytes = 0;
+  let totalLines = 0;
+  let more = false;
+  let byteCap = false;
+  const signalOpt = {};
+  if (opts.signal !== void 0) signalOpt.signal = opts.signal;
+  const iter = ops.openLineStream(path4, signalOpt);
+  for await (const raw of iter) {
+    totalLines += 1;
+    if (totalLines <= start) continue;
+    if (out.length >= opts.limit) {
+      more = true;
+      continue;
+    }
+    const truncated = raw.length > maxLineLen ? raw.substring(0, maxLineLen) + MAX_LINE_SUFFIX : raw;
+    const size = buffer.Buffer.byteLength(truncated, "utf8") + (out.length > 0 ? 1 : 0);
+    if (bytes + size > maxBytes) {
+      byteCap = true;
+      more = true;
+      break;
+    }
+    out.push(truncated);
+    bytes += size;
+  }
+  return {
+    lines: out,
+    totalLines,
+    offset: opts.offset,
+    more,
+    byteCap
+  };
+}
+var ReadParamsSchema = v__namespace.object({
+  path: v__namespace.pipe(v__namespace.string(), v__namespace.minLength(1, "path must not be empty")),
+  offset: v__namespace.optional(
+    v__namespace.pipe(v__namespace.number(), v__namespace.integer(), v__namespace.minValue(1, "offset must be >= 1"))
+  ),
+  limit: v__namespace.optional(
+    v__namespace.pipe(v__namespace.number(), v__namespace.integer(), v__namespace.minValue(1, "limit must be >= 1"))
+  )
+});
+function parseReadParams(input) {
+  return v__namespace.parse(ReadParamsSchema, input);
+}
+function safeParseReadParams(input) {
+  const result = v__namespace.safeParse(ReadParamsSchema, input);
+  if (result.success) return { ok: true, value: result.output };
+  return { ok: false, issues: result.issues };
+}
+var READ_TOOL_NAME = "read";
+var READ_TOOL_DESCRIPTION = `Read a file or directory from the local filesystem.
+
+Usage:
+- The path parameter should be an absolute path. If relative, it resolves against the session working directory.
+- By default, returns up to 2000 lines from the start of the file.
+- The offset parameter is the 1-indexed line number to start from.
+- For later sections, call this tool again with a larger offset.
+- Use the grep tool for content search in large files; glob to locate files by pattern.
+- Contents are returned with each line prefixed by its line number as "<line>: <content>".
+- Any line longer than 2000 characters is truncated.
+- Call this tool in parallel when reading multiple files.
+- Avoid tiny repeated slices (under 30 lines). Read a larger window instead.
+- Images and PDFs are returned as file attachments.
+- Binary files are refused; use specialized tools.`;
+var readToolDefinition = {
+  name: READ_TOOL_NAME,
+  description: READ_TOOL_DESCRIPTION,
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Absolute path (preferred) or path relative to the session cwd."
+      },
+      offset: {
+        type: "integer",
+        minimum: 1,
+        description: "1-indexed line number to start reading from."
+      },
+      limit: {
+        type: "integer",
+        minimum: 1,
+        description: "Maximum number of lines to read. Defaults to 2000."
+      }
+    },
+    required: ["path"],
+    additionalProperties: false
+  }
+};
+async function suggestSiblings(ops, missingPath) {
+  const dir = path3__default.default.dirname(missingPath);
+  const base = path3__default.default.basename(missingPath).toLowerCase();
+  let entries;
+  try {
+    entries = await ops.readDirectory(dir);
+  } catch {
+    return [];
+  }
+  const scored = [];
+  for (const entry of entries) {
+    const lower = entry.toLowerCase();
+    const score = similarity(base, lower);
+    if (score > 0) scored.push({ p: path3__default.default.join(dir, entry), score });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, FUZZY_SUGGESTION_LIMIT).map((s) => s.p);
+}
+function similarity(a, b) {
+  if (a === b) return 1e3;
+  if (a.length === 0 || b.length === 0) return 0;
+  if (a.includes(b) || b.includes(a)) return 500;
+  const prefix = commonPrefix(a, b);
+  if (prefix >= 3) return 200 + prefix;
+  if (prefix >= 2 && Math.abs(a.length - b.length) <= 2) return 100 + prefix;
+  const aExt = extOf(a);
+  const bExt = extOf(b);
+  if (aExt && aExt === bExt) return 10;
+  return 0;
+}
+function commonPrefix(a, b) {
+  const n = Math.min(a.length, b.length);
+  let i = 0;
+  while (i < n && a[i] === b[i]) i++;
+  return i;
+}
+function extOf(name) {
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot) : "";
+}
+
+// src/read.ts
+function err(error) {
+  return { kind: "error", error };
+}
+async function read(input, session) {
+  const parsed = safeParseReadParams(input);
+  if (!parsed.ok) {
+    const messages = parsed.issues.map((i) => i.message).join("; ");
+    return err(harnessCore.toolError("INVALID_PARAM", messages, { cause: parsed.issues }));
+  }
+  const params = parsed.value;
+  const ops = session.ops ?? harnessCore.defaultNodeOperations();
+  const resolvedPath = await resolvePath(ops, session.cwd, params.path);
+  const fence = await fencePath(ops, session, resolvedPath);
+  if (fence !== void 0) return err(fence);
+  return harnessCore.withFileLock(
+    resolvedPath,
+    () => executeRead(ops, session, resolvedPath, params)
+  );
+}
+async function resolvePath(ops, cwd, input) {
+  const absolute = path3__default.default.isAbsolute(input) ? input : path3__default.default.resolve(cwd, input);
+  try {
+    return await ops.realpath(absolute);
+  } catch {
+    return absolute;
+  }
+}
+async function fencePath(ops, session, resolvedPath) {
+  const { permissions } = session;
+  const isSensitive = harnessCore.matchesAnyPattern(
+    resolvedPath,
+    permissions.sensitivePatterns
+  );
+  const insideWorkspace = harnessCore.isInsideAnyRoot(resolvedPath, permissions.roots);
+  const needsAsk = isSensitive || !insideWorkspace && permissions.bypassWorkspaceGuard !== true;
+  if (isSensitive && permissions.hook === void 0) {
+    return harnessCore.toolError(
+      "SENSITIVE",
+      `Refusing to read sensitive path: ${resolvedPath}`,
+      { meta: { path: resolvedPath } }
+    );
+  }
+  if (!insideWorkspace && permissions.bypassWorkspaceGuard !== true && permissions.hook === void 0) {
+    if (process.env.E2E_DEBUG_PERMISSIONS) {
+      console.error(
+        `[read fencePath] OUTSIDE_WORKSPACE reject: resolvedPath=${JSON.stringify(resolvedPath)} roots=${JSON.stringify(permissions.roots)}`
+      );
+    }
+    return harnessCore.toolError(
+      "OUTSIDE_WORKSPACE",
+      `Path is outside all configured workspace roots: ${resolvedPath}`,
+      { meta: { path: resolvedPath, roots: permissions.roots } }
+    );
+  }
+  if (permissions.hook !== void 0) {
+    const reason = isSensitive ? "sensitive" : !insideWorkspace ? "outside_workspace" : "in_workspace";
+    const alwaysPatterns = needsAsk ? [path3__default.default.dirname(resolvedPath) + "/*"] : ["*"];
+    const decision = await permissions.hook({
+      tool: "read",
+      path: resolvedPath,
+      action: "read",
+      always_patterns: alwaysPatterns,
+      metadata: { reason }
+    });
+    if (decision === "deny") {
+      return harnessCore.toolError(
+        "PERMISSION_DENIED",
+        `Read denied by user: ${resolvedPath}`,
+        { meta: { path: resolvedPath } }
+      );
+    }
+  }
+  return void 0;
+}
+async function executeRead(ops, session, resolvedPath, params) {
+  let stat;
+  try {
+    stat = await ops.stat(resolvedPath);
+  } catch (e) {
+    return err(
+      harnessCore.toolError("IO_ERROR", `stat failed: ${e.message}`, {
+        cause: e
+      })
+    );
+  }
+  if (!stat) {
+    const suggestions = await suggestSiblings(ops, resolvedPath);
+    const msg = suggestions.length > 0 ? `File not found: ${resolvedPath}
+
+Did you mean one of these?
+${suggestions.join("\n")}` : `File not found: ${resolvedPath}`;
+    return err(
+      harnessCore.toolError("NOT_FOUND", msg, { meta: { path: resolvedPath, suggestions } })
+    );
+  }
+  if (stat.type === "directory") {
+    return readDirectory(ops, resolvedPath, params);
+  }
+  const maxSize = session.maxFileSize ?? MAX_FILE_SIZE;
+  if (stat.size > maxSize) {
+    return err(
+      harnessCore.toolError(
+        "TOO_LARGE",
+        `File size ${stat.size} exceeds max ${maxSize}. Use a narrower offset/limit or grep first.`,
+        { meta: { path: resolvedPath, size: stat.size, maxSize } }
+      )
+    );
+  }
+  const half = session.modelContextTokens ? Math.floor(session.modelContextTokens / 2) : void 0;
+  const tokensPerByte = session.tokensPerByte ?? 0.3;
+  if (half !== void 0 && stat.size * tokensPerByte > half) {
+    return err(
+      harnessCore.toolError(
+        "TOO_LARGE",
+        `File would consume more than half of the model context (~${Math.floor(stat.size * tokensPerByte)} tokens > ${half}). Use offset/limit or grep first.`,
+        { meta: { path: resolvedPath, size: stat.size, half } }
+      )
+    );
+  }
+  const mime = ops.mimeType(resolvedPath);
+  if (isImageMime(mime) || isPdfMime(mime)) {
+    return readAttachment(ops, resolvedPath, mime, stat.size);
+  }
+  const sample = await readSample(ops, resolvedPath, stat.size);
+  if (isBinary(resolvedPath, sample)) {
+    return err(
+      harnessCore.toolError("BINARY", `Cannot read binary file: ${resolvedPath}`, {
+        meta: { path: resolvedPath }
+      })
+    );
+  }
+  return readText(ops, session, resolvedPath, stat, params);
+}
+async function readSample(ops, p, size) {
+  if (size === 0) return new Uint8Array();
+  const bytes = await ops.readFile(p);
+  return bytes.length > BINARY_SAMPLE_BYTES ? bytes.subarray(0, BINARY_SAMPLE_BYTES) : bytes;
+}
+async function readDirectory(ops, resolvedPath, params) {
+  const entries = await ops.readDirectoryEntries(resolvedPath);
+  const named = await Promise.all(
+    entries.map(async (e) => {
+      if (e.type === "directory") return e.name + "/";
+      if (e.type !== "symlink") return e.name;
+      const target = await ops.stat(path3__default.default.join(resolvedPath, e.name)).catch(() => void 0);
+      return target?.type === "directory" ? e.name + "/" : e.name;
+    })
+  );
+  named.sort((a, b) => a.localeCompare(b, void 0, { sensitivity: "base" }));
+  const offset = params.offset ?? 1;
+  const limit = params.limit ?? DEFAULT_LIMIT;
+  const start = offset - 1;
+  const sliced = named.slice(start, start + limit);
+  const more = start + sliced.length < named.length;
+  const output = formatDirectory({
+    path: resolvedPath,
+    entries: sliced,
+    offset,
+    totalEntries: named.length,
+    more
+  });
+  return {
+    kind: "directory",
+    output,
+    meta: {
+      path: resolvedPath,
+      totalEntries: named.length,
+      returnedEntries: sliced.length,
+      offset,
+      limit,
+      more
+    }
+  };
+}
+async function readAttachment(ops, resolvedPath, mime, size) {
+  const bytes = await ops.readFile(resolvedPath);
+  const kind = mime === "application/pdf" ? "PDF" : "Image";
+  const dataUrl = `data:${mime};base64,${buffer.Buffer.from(bytes).toString("base64")}`;
+  return {
+    kind: "attachment",
+    output: formatAttachment(kind),
+    attachments: [{ mime, dataUrl }],
+    meta: { path: resolvedPath, mime, size_bytes: size }
+  };
+}
+async function readText(ops, session, resolvedPath, stat, params) {
+  const offset = params.offset ?? 1;
+  const limit = params.limit ?? session.defaultLimit ?? DEFAULT_LIMIT;
+  if (session.cache) {
+    const cached = session.cache.get({
+      path: resolvedPath,
+      mtime_ms: stat.mtime_ms,
+      size_bytes: stat.size,
+      offset,
+      limit
+    });
+    if (cached) {
+      if (session.ledger) {
+        session.ledger.record({
+          path: resolvedPath,
+          sha256: cached.meta.sha256,
+          mtime_ms: stat.mtime_ms,
+          size_bytes: stat.size,
+          lines_returned: cached.meta.returnedLines,
+          offset,
+          limit,
+          timestamp_ms: Date.now()
+        });
+      }
+      return cached;
+    }
+  }
+  const lineStreamOpts = { offset, limit };
+  if (session.maxBytes !== void 0) lineStreamOpts.maxBytes = session.maxBytes;
+  if (session.maxLineLength !== void 0)
+    lineStreamOpts.maxLineLength = session.maxLineLength;
+  if (session.signal !== void 0) lineStreamOpts.signal = session.signal;
+  const result = await streamLines(ops, resolvedPath, lineStreamOpts);
+  if (result.totalLines > 0 && offset > result.totalLines) {
+    return err(
+      harnessCore.toolError(
+        "INVALID_PARAM",
+        `Offset ${offset} is out of range for this file (${result.totalLines} lines)`,
+        { meta: { path: resolvedPath, totalLines: result.totalLines } }
+      )
+    );
+  }
+  const bytes = await ops.readFile(resolvedPath);
+  const sha256 = crypto.createHash("sha256").update(bytes).digest("hex");
+  const output = formatText({
+    path: resolvedPath,
+    offset,
+    lines: result.lines,
+    totalLines: result.totalLines,
+    more: result.more,
+    byteCap: result.byteCap
+  });
+  const textResult = {
+    kind: "text",
+    output,
+    meta: {
+      path: resolvedPath,
+      totalLines: result.totalLines,
+      returnedLines: result.lines.length,
+      offset,
+      limit,
+      byteCap: result.byteCap,
+      more: result.more,
+      sha256,
+      mtime_ms: stat.mtime_ms,
+      size_bytes: stat.size
+    }
+  };
+  if (session.cache) {
+    session.cache.set(
+      {
+        path: resolvedPath,
+        mtime_ms: stat.mtime_ms,
+        size_bytes: stat.size,
+        offset,
+        limit
+      },
+      textResult
+    );
+  }
+  if (session.ledger) {
+    session.ledger.record({
+      path: resolvedPath,
+      sha256,
+      mtime_ms: stat.mtime_ms,
+      size_bytes: stat.size,
+      lines_returned: result.lines.length,
+      offset,
+      limit,
+      timestamp_ms: Date.now()
+    });
+  }
+  return textResult;
+}
+
+exports.BINARY_EXTENSIONS = BINARY_EXTENSIONS;
+exports.DEFAULT_LIMIT = DEFAULT_LIMIT;
+exports.MAX_BYTES = MAX_BYTES;
+exports.MAX_FILE_SIZE = MAX_FILE_SIZE;
+exports.MAX_LINE_LENGTH = MAX_LINE_LENGTH;
+exports.READ_TOOL_DESCRIPTION = READ_TOOL_DESCRIPTION;
+exports.READ_TOOL_NAME = READ_TOOL_NAME;
+exports.ReadParamsSchema = ReadParamsSchema;
+exports.formatAttachment = formatAttachment;
+exports.formatDirectory = formatDirectory;
+exports.formatText = formatText;
+exports.isBinary = isBinary;
+exports.isBinaryByContent = isBinaryByContent;
+exports.isBinaryByExtension = isBinaryByExtension;
+exports.isImageMime = isImageMime;
+exports.isPdfMime = isPdfMime;
+exports.parseReadParams = parseReadParams;
+exports.read = read;
+exports.readToolDefinition = readToolDefinition;
+exports.safeParseReadParams = safeParseReadParams;
+exports.streamLines = streamLines;
+exports.suggestSiblings = suggestSiblings;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map