path: root/agent/tools/read.lua

-- Read a file from disk and return its text verbatim.
--
-- Output cap: 50 KB and 2000 lines, whichever is hit first. Large
-- enough to be useful, small enough to keep the model's context
-- manageable. A single tool result that blows out the context window is
-- worse than one that silently asks for a follow-up scoped read.
--
-- The slicing knobs are `offset` (1-based line to start at) and
-- `limit` (max lines to return). SQL-shaped — models recognize the
-- idiom. When the cap is hit, a `[truncated: ...]` marker names the
-- next `offset` for a follow-up call.
--
-- If `path` names a directory, return a clearly tagged non-recursive
-- listing of its immediate children instead of an error.

local uv = require("luv")

local MAX_BYTES = 50 * 1024   -- 50 KB
local MAX_LINES = 2000
local READ_CHUNK_SIZE = MAX_BYTES

local function scandir_sorted(path)
    local req, err = uv.fs_scandir(path)
    if not req then
        return nil, err
    end

    local entries = {}
    while true do
        local name, typ = uv.fs_scandir_next(req)
        if not name then break end
        entries[#entries + 1] = { name = name, typ = typ }
    end

    table.sort(entries, function(a, b)
        return a.name < b.name
    end)
    return entries
end

local function render_directory_listing(path, offset, limit)
    local entries, err = scandir_sorted(path)
    if not entries then
        return "Error: " .. (err or ("could not list directory " .. path))
    end

    local total = #entries
    if total == 0 then
        return string.format("[directory listing for %s]\n(empty directory)\n", path)
    end
    if offset > total then
        return string.format(
            "Error: offset (%d) is past end of directory listing (%d entries).",
            offset, total
        )
    end

    local effective_line_cap = MAX_LINES
    if limit and limit < effective_line_cap then
        effective_line_cap = limit
    end

    local parts = {
        string.format("[directory listing for %s]\n", path),
    }
    local emitted_lines = 0
    local emitted_bytes = #parts[1]
    local truncated_reason = nil
    local stopped_at_entry = nil

    for idx = offset, total do
        local entry = entries[idx]
        local rendered = string.format("%s\t%s\n", entry.typ or "unknown", entry.name)
        if emitted_bytes + #rendered > MAX_BYTES then
            truncated_reason = "bytes"
            stopped_at_entry = idx
            break
        end
        parts[#parts + 1] = rendered
        emitted_bytes = emitted_bytes + #rendered
        emitted_lines = emitted_lines + 1

        if emitted_lines >= effective_line_cap then
            if idx < total then
                truncated_reason = (limit and limit <= MAX_LINES) and "limit" or "lines"
                stopped_at_entry = idx
            end
            break
        end
    end

    local body = table.concat(parts)
    if truncated_reason == "bytes" then
        body = body .. string.format(
            "\n[truncated directory listing: hit %d-byte cap at entry %d. " ..
            "Call `read` again with `offset = %d` (and a smaller `limit` if needed) to continue.]\n",
            MAX_BYTES, stopped_at_entry, stopped_at_entry
        )
    elseif truncated_reason == "lines" then
        body = body .. string.format(
            "\n[truncated directory listing: hit %d-line cap at entry %d. " ..
            "Call `read` again with `offset = %d` to continue.]\n",
            MAX_LINES, stopped_at_entry, stopped_at_entry + 1
        )
    elseif truncated_reason == "limit" then
        body = body .. string.format(
            "\n[truncated directory listing: hit caller's `limit = %d` at entry %d. " ..
            "Call `read` again with `offset = %d` to continue.]\n",
            limit, stopped_at_entry, stopped_at_entry + 1
        )
    end
    return body
end

return {
    name = "std.read",
    description = "Read a file from disk. Output is truncated to the first 50KB or 2000 lines, whichever is hit first; directories return a clearly tagged non-recursive listing. Use offset/limit to slice.",
    schema = {
        type = "object",
        properties = {
            path = { type = "string", description = "Path to the file or directory (relative or absolute)." },
            offset = { type = "integer", description = "1-based line to start at.", minimum = 1 },
            limit = { type = "integer", description = "Maximum lines to return.", minimum = 1 },
        },
        required = { "path" },
    },
    handler = function(input)
        local path = input.path
        local offset = input.offset or 1
        local limit = input.limit  -- nil means "to EOF"

        if type(path) ~= "string" or path == "" then
            return "Error: `path` must be a non-empty string."
        end
        if limit ~= nil and limit < 1 then
            return string.format("Error: limit (%d) must be >= 1.", limit)
        end

        local stat, stat_err = uv.fs_stat(path)
        if not stat then
            return "Error: " .. (stat_err or ("could not stat " .. path))
        end
        if stat.type == "directory" then
            return render_directory_listing(path, offset, limit)
        end

        local fd, open_err = uv.fs_open(path, "r", 0)
        if not fd then
            return "Error: " .. (open_err or ("could not open " .. path))
        end

        local parts = {}
        local emitted_lines = 0
        local emitted_bytes = 0
        local lineno = 0
        local truncated_reason = nil
        local stopped_at_line = nil
        local effective_line_cap = MAX_LINES
        if limit and limit < effective_line_cap then
            effective_line_cap = limit
        end

        local file_offset = 0
        local done = false
        local read_err = nil
        local saw_any_bytes = false
        local saw_trailing_newline = false

        local carry = ""
        local function process_line(line)
            lineno = lineno + 1
            if lineno < offset then
                return
            end

            local rendered = line .. "\n"
            if emitted_bytes + #rendered > MAX_BYTES then
                truncated_reason = "bytes"
                stopped_at_line = lineno
                done = true
                return
            end
            parts[#parts + 1] = rendered
            emitted_bytes = emitted_bytes + #rendered
            emitted_lines = emitted_lines + 1
            if emitted_lines >= effective_line_cap then
                stopped_at_line = lineno
                done = true
            end
        end

        while not done do
            local data, err = uv.fs_read(fd, READ_CHUNK_SIZE, file_offset)
            if err then
                read_err = err
                break
            end
            if data == nil then
                if #carry > 0 then
                    process_line(carry)
                    carry = ""
                end
                break
            end

            saw_any_bytes = true
            file_offset = file_offset + #data
            saw_trailing_newline = data:sub(-1) == "\n"
            local chunk = carry .. data
            local start = 1

            while not done do
                local nl = chunk:find("\n", start, true)
                if not nl then break end
                local line = chunk:sub(start, nl - 1)
                if line:sub(-1) == "\r" then
                    line = line:sub(1, -2)
                end
                process_line(line)
                start = nl + 1
            end

            carry = chunk:sub(start)
            if done and truncated_reason == nil and emitted_lines >= effective_line_cap then
                truncated_reason = (limit and limit <= MAX_LINES) and "limit" or "lines"
            end
        end

        uv.fs_close(fd)

        if read_err then
            return "Error: read failed: " .. tostring(read_err)
        end

        if #parts == 0 then
            if not saw_any_bytes then
                return "(empty file)\n"
            end
            if offset > lineno then
                return string.format(
                    "Error: offset (%d) is past end of file (%d lines).",
                    offset, lineno
                )
            end
            if lineno == 0 and saw_any_bytes and not saw_trailing_newline then
                return "(empty file)\n"
            end
            return "(no lines in requested range)\n"
        end

        local body = table.concat(parts)
        if truncated_reason == "bytes" then
            body = body .. string.format(
                "\n[truncated: hit %d-byte cap at line %d. " ..
                "Call `read` again with `offset = %d` (and a smaller " ..
                "`limit` if needed) to continue.]\n",
                MAX_BYTES, stopped_at_line, stopped_at_line
            )
        elseif truncated_reason == "lines" then
            body = body .. string.format(
                "\n[truncated: hit %d-line cap at line %d. " ..
                "Call `read` again with `offset = %d` to continue.]\n",
                MAX_LINES, stopped_at_line, stopped_at_line + 1
            )
        elseif truncated_reason == "limit" then
            body = body .. string.format(
                "\n[truncated: hit caller's `limit = %d` at line %d. " ..
                "Call `read` again with `offset = %d` to continue.]\n",
                limit, stopped_at_line, stopped_at_line + 1
            )
        end
        return body
    end,
}