path: root/agent/tools/read.lua

local std = require("_std")

local tool = {
    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. Works with images and PDFs.",
    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" },
    },
}

-- 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.

-- Minimal magic-byte sniff: binary attachment (image/PDF) vs. text.
-- We only decide *whether* the bytes are an attachment; libpanto does the
-- precise type detection, resizing, and encoding from the raw bytes. Keep
-- this in lockstep with `code.tjp.lol/libpantograph.git/src/image.zig`'s `detectCodec`.
local function is_attachment(head)
    local b = { head:byte(1, 12) }
    -- PNG: 89 50 4E 47 0D 0A 1A 0A
    if b[1] == 0x89 and b[2] == 0x50 and b[3] == 0x4E and b[4] == 0x47
        and b[5] == 0x0D and b[6] == 0x0A and b[7] == 0x1A and b[8] == 0x0A then
        return true
    end
    -- JPEG: FF D8 FF
    if b[1] == 0xFF and b[2] == 0xD8 and b[3] == 0xFF then return true end
    -- GIF: "GIF87a" / "GIF89a"
    if head:sub(1, 6) == "GIF87a" or head:sub(1, 6) == "GIF89a" then return true end
    -- BMP: "BM"
    if b[1] == 0x42 and b[2] == 0x4D then return true end
    -- WEBP: "RIFF"????"WEBP"
    if head:sub(1, 4) == "RIFF" and head:sub(9, 12) == "WEBP" then return true end
    -- PDF: "%PDF-"
    if head:sub(1, 5) == "%PDF-" then return true end
    return false
end

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

-- `uv.fs_opendir` takes the entries-per-readdir batch hint as its
-- SECOND positional arg, before the callback. We pass it explicitly so
-- each `fs_readdir` returns up to `n` entries per round-trip.
local READDIR_BATCH = 256

local function scandir_sorted(path)
    -- Use the streaming opendir/readdir/closedir API rather than
    -- `fs_scandir` + `fs_scandir_next`: the latter's iterator advances
    -- with synchronous `readdir(3)` syscalls, which would block the
    -- shared event loop on large directories. opendir/readdir route
    -- every batch through libuv's thread pool, keeping us cooperative.
    local err, dir = std.fs_opendir(path, READDIR_BATCH)
    if not dir then
        return nil, err
    end

    local entries = {}
    while true do
        local rerr, batch = std.fs_readdir(dir)
        if rerr then
            std.fs_closedir(dir)
            return nil, rerr
        end
        -- A nil/empty batch signals end of the directory stream.
        if batch == nil or #batch == 0 then break end
        for _, e in ipairs(batch) do
            -- async readdir yields { name = ..., type = ... }.
            entries[#entries + 1] = { name = e.name, typ = e.type }
        end
    end
    std.fs_closedir(dir)

    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

tool.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_err, stat = std.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 open_err, fd = std.fs_open(path, "r", 0)
    if not fd then
        return "Error: " .. (open_err or ("could not open " .. path))
    end

    -- Binary attachment path. We do the *minimal* magic-byte sniff
    -- here — only enough to decide "binary attachment vs. text". If
    -- it's an attachment, we return the raw file bytes; libpanto does
    -- the real work (precise type detection, resizing, encoding).
    do
        local herr, header = std.fs_read(fd, 16, 0)
        if not herr and header and #header > 0 and is_attachment(header) then
            local whole, rerr = (function()
                local chunks = {}
                local off = 0
                while true do
                    local e, d = std.fs_read(fd, READ_CHUNK_SIZE, off)
                    if e then return nil, e end
                    if d == nil or #d == 0 then break end
                    chunks[#chunks + 1] = d
                    off = off + #d
                end
                return table.concat(chunks)
            end)()
            std.fs_close(fd)
            if not whole then
                return "Error: read failed: " .. tostring(rerr)
            end
            return {
                text = string.format("[read %s as binary attachment]", path),
                attachments = { { data = whole } },
            }
        end
    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 err, data = std.fs_read(fd, READ_CHUNK_SIZE, file_offset)
        if err then
            read_err = err
            break
        end
        -- luv's `fs_read` signals EOF by returning the empty
        -- string, NOT nil (nil only accompanies an error). Treat
        -- both nil and "" as EOF; otherwise the loop re-reads at
        -- the same offset forever, pinning a core at 100%.
        if data == nil or #data == 0 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

    std.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

local function quote(v)
    if v == nil or v == "" then return nil end
    return tostring(v)
end

std.install_renderer(tool.name, function(st)
    local obj = std.decode(st.input)
    local path = obj and quote(obj.path)
    if not path then return "read" end
    if type(obj.offset) == "number" and type(obj.limit) == "number" then
        return string.format("read %s (lines %d-%d)", path, obj.offset, obj.offset + obj.limit - 1)
    elseif type(obj.offset) == "number" then
        return string.format("read %s (from line %d)", path, obj.offset)
    end
    return "read " .. path
end)

return tool