path: root/agent/tools/shell.lua

-- Run a shell command and return its merged stdout+stderr output.
--
-- The command is executed via `/bin/sh -c <command>`, so shell
-- features (pipes, redirections, globs, `&&`, etc.) all work the
-- usual way. Stdin is closed; the command cannot read from the
-- terminal.
--
-- Context-budget discipline:
--   - Output is capped at 50 KB (matching `read`'s cap), keeping the
--     **last** 50 KB on overflow. Compiler errors, test failures, and
--     stack traces all put the important content at the end, so a
--     head-keeping shell tool routinely truncates exactly the bytes
--     the agent needed.
--   - Once overflow is detected, the *complete* transcript is
--     streamed to a spill file under `$PANTO_HOME/shell-output/`. The
--     agent can then `read` it with start_line/end_line to inspect
--     specific regions — including the head that fell out of the
--     tail buffer.
--
-- Timeout: defaults to 30s. When the timer fires the child gets
-- SIGTERM; if it still hasn't exited 250 ms later, SIGKILL.
--
-- Stdout and stderr are merged into a single stream (in arrival
-- order). Distinguishing them would require either prefixing every
-- chunk (visually noisy) or surfacing two separate strings (not how
-- a string-returning tool result is shaped). Most shell commands the
-- agent runs interleave the two anyway.

local uv = require("luv")

local MAX_BYTES = 50 * 1024   -- 50 KB, same as `read`
local DEFAULT_TIMEOUT_S = 300   -- 5 minutes
local SIGKILL_GRACE_MS = 250

-- ---------------------------------------------------------------------------
-- Spill-file path resolution. We mirror Zig's `panto_home.resolveHome`:
-- PANTO_HOME wins, then XDG_DATA_HOME/panto, then HOME/.local/share/panto.
-- The shell-output subdirectory is created lazily.
-- ---------------------------------------------------------------------------

local function panto_home()
    local p = os.getenv("PANTO_HOME")
    if p and p ~= "" then return p end
    local xdg = os.getenv("XDG_DATA_HOME")
    if xdg and xdg ~= "" then return xdg .. "/panto" end
    local home = os.getenv("HOME")
    if home and home ~= "" then return home .. "/.local/share/panto" end
    return nil
end

local function spill_dir()
    local base = panto_home()
    if not base then return nil end
    return base .. "/shell-output"
end

-- `mkdir -p`-equivalent via luv. We can't shell out to mkdir here —
-- that would be circular — so we walk the path components and call
-- `uv.fs_mkdir` on each, ignoring EEXIST. Synchronous; this is a
-- once-per-spill cost.
local function mkdir_p(path)
    -- Split on `/` and rebuild. Absolute paths start with "/"; preserve.
    local parts = {}
    for piece in string.gmatch(path, "[^/]+") do
        parts[#parts + 1] = piece
    end
    local cur = (path:sub(1, 1) == "/") and "" or "."
    for _, piece in ipairs(parts) do
        cur = cur .. "/" .. piece
        local ok, err, name = uv.fs_mkdir(cur, tonumber("755", 8))
        if not ok and name ~= "EEXIST" then
            return nil, err
        end
    end
    return true
end

local function fresh_spill_path()
    local dir = spill_dir()
    if not dir then return nil, "no PANTO_HOME / XDG_DATA_HOME / HOME in env" end
    local ok, err = mkdir_p(dir)
    if not ok then return nil, err end
    -- Filename: <unix-seconds>-<microseconds>-<pid>.txt. The pid is
    -- the parent panto process; collision avoidance against concurrent
    -- tool calls comes from the microsecond component (uv.hrtime() is
    -- nanoseconds since some epoch).
    local sec, usec = uv.gettimeofday()
    local pid = uv.os_getpid()
    return string.format("%s/%d-%06d-%d.txt", dir, sec, usec, pid)
end

-- ---------------------------------------------------------------------------
-- Tool body
-- ---------------------------------------------------------------------------

return {
    name = "std.shell",
    description = string.format("Execute a shell command via `/bin/sh -c`. Returns merged stdout+stderr after the command exits, prefixed with an exit-status header. Output is truncated to the last %dKB; on truncation the full transcript is saved to `$PANTO_HOME/shell-output/` and its path is included for follow-up `read` calls. Default timeout 5 minutes.", MAX_BYTES / 1024),
    schema = {
        type = "object",
        properties = {
            command = { type = "string", description = "Shell command. Passed to `sh -c` verbatim; pipes, redirections, etc. work." },
            cwd = { type = "string", description = "Working directory (default: cwd)." },
            timeout = { type = "integer", description = "Hard timeout in seconds (default: " .. tostring(DEFAULT_TIMEOUT_S) .. ").", minimum = 1 },
        },
        required = { "command" },
    },
    handler = function(input)
        local command = input.command
        if type(command) ~= "string" or command == "" then
            return "Error: `command` must be a non-empty string."
        end
        local cwd = input.cwd
        if cwd ~= nil and type(cwd) ~= "string" then
            return "Error: `cwd` must be a string if provided."
        end
        local timeout_s = input.timeout or DEFAULT_TIMEOUT_S
        local timeout_ms = timeout_s * 1000

        local co = coroutine.running()
        if not co then
            -- Should never happen — panto always runs handlers in a
            -- coroutine — but be defensive rather than silently hang.
            return "Error: shell tool requires a coroutine scheduler " ..
                "(internal bug; report to panto)."
        end

        -- Pipes for the child's stdout/stderr. Stdin is `nil` in the
        -- stdio table → child reads from /dev/null equivalent (luv
        -- closes that fd in the child).
        local stdout_pipe = uv.new_pipe(false)
        local stderr_pipe = uv.new_pipe(false)

        -- Output accumulator: a FIFO of arrival-order chunks whose
        -- total length is always ≤ MAX_BYTES. On overflow we evict
        -- from the front (oldest bytes first) so the in-memory buffer
        -- always holds the *tail* of the output. The full unabridged
        -- transcript is mirrored to a spill file, opened lazily on
        -- first overflow and pre-loaded with everything seen so far.
        local chunks = {}          -- FIFO of strings; total ≤ MAX_BYTES
        local first = 1            -- index of oldest live chunk in `chunks`
        local last = 0             -- index of newest live chunk
        local total_bytes = 0
        local total_received = 0   -- everything we ever saw, pre-eviction
        local overflowed = false   -- true once a byte has been evicted
        local spill_path = nil
        local spill_handle = nil   -- uv fd (integer) once opened
        local spill_error = nil    -- if opening/writing the spill file fails
        local total_written_to_spill = 0

        local function open_spill_and_seed()
            -- Opens the spill file and writes every chunk currently
            -- live in the FIFO. Called exactly once, the moment we
            -- realize we're going to overflow. After this returns,
            -- the spill file contains the entire history; every
            -- subsequent chunk just appends.
            if spill_handle or spill_error then return end
            local path, err = fresh_spill_path()
            if not path then
                spill_error = err
                return
            end
            -- O_WRONLY | O_CREAT | O_TRUNC; mode 0644.
            local fd, oerr = uv.fs_open(path, "w", tonumber("644", 8))
            if not fd then
                spill_error = oerr or "unknown error opening spill file"
                return
            end
            spill_path = path
            spill_handle = fd
            for i = first, last do
                local c = chunks[i]
                local n, werr = uv.fs_write(fd, c, -1)
                if not n then
                    spill_error = werr or "spill write failed"
                    return
                end
                total_written_to_spill = total_written_to_spill + n
            end
        end

        local function spill_write(data)
            if not spill_handle then return end
            local n, werr = uv.fs_write(spill_handle, data, -1)
            if not n then
                spill_error = spill_error or werr or "spill write failed"
            else
                total_written_to_spill = total_written_to_spill + n
            end
        end

        local function append_chunk(data)
            total_received = total_received + #data

            -- First time we'd cross MAX_BYTES: open the spill file
            -- and seed it with everything we've buffered so far. From
            -- here on we always dual-write (spill gets the unabridged
            -- stream; chunks holds only the tail).
            if not overflowed and total_bytes + #data > MAX_BYTES then
                overflowed = true
                open_spill_and_seed()
            end
            if overflowed then
                spill_write(data)
            end

            -- Append to the ring. If the new chunk alone is bigger
            -- than MAX_BYTES, drop everything we have and keep just
            -- its tail. Otherwise, evict whole front chunks until
            -- there's room, then either trim the front-most or
            -- append intact.
            if #data >= MAX_BYTES then
                -- Drop the whole FIFO; new chunk is the tail.
                for i = first, last do chunks[i] = nil end
                first = last + 1
                total_bytes = 0
                local trimmed = data:sub(#data - MAX_BYTES + 1)
                last = last + 1
                chunks[last] = trimmed
                total_bytes = #trimmed
                return
            end

            while total_bytes + #data > MAX_BYTES and first <= last do
                local front = chunks[first]
                if total_bytes - #front + #data <= MAX_BYTES then
                    -- Trim the front chunk: drop only as many bytes
                    -- as needed to make room.
                    local need_to_drop = (total_bytes + #data) - MAX_BYTES
                    chunks[first] = front:sub(need_to_drop + 1)
                    total_bytes = total_bytes - need_to_drop
                else
                    -- Drop the entire front chunk.
                    chunks[first] = nil
                    total_bytes = total_bytes - #front
                    first = first + 1
                end
            end
            last = last + 1
            chunks[last] = data
            total_bytes = total_bytes + #data
        end

        -- Coordination state. We resume the coroutine exactly once,
        -- after `pending_events` hits zero: stdout EOF, stderr EOF,
        -- on_exit fired = 3 events.
        local pending_events = 3
        local resumed = false
        local exit_code = nil
        local exit_signal = nil
        local timed_out = false
        local spawn_error = nil
        local process_handle = nil
        local timeout_timer = nil
        local kill_timer = nil

        local function buffer_to_string()
            local out = {}
            local oi = 0
            for i = first, last do
                oi = oi + 1
                out[oi] = chunks[i]
            end
            return table.concat(out)
        end

        local function try_resume()
            if pending_events > 0 then return end
            if resumed then return end
            resumed = true
            -- Cancel any still-pending timers. They may have been
            -- nil'd out already inside their own callback.
            if timeout_timer and not timeout_timer:is_closing() then
                timeout_timer:stop(); timeout_timer:close()
            end
            if kill_timer and not kill_timer:is_closing() then
                kill_timer:stop(); kill_timer:close()
            end
            local ok, err = coroutine.resume(co)
            if not ok then
                -- The handler shouldn't be raising here; this is the
                -- resume scheduler, not user code. Log via stderr;
                -- the parent will surface the failure as a tool error.
                io.stderr:write("shell tool: resume failed: " .. tostring(err) .. "\n")
            end
        end

        local function on_read(err, data)
            if err then
                -- Treat read errors as EOF — luv signals EOF by
                -- calling with `data == nil`, so an actual `err` means
                -- something genuinely broke. Record it once.
                append_chunk("[read error: " .. tostring(err) .. "]\n")
                pending_events = pending_events - 1
                try_resume()
                return
            end
            if data == nil then
                -- EOF on this pipe.
                pending_events = pending_events - 1
                try_resume()
                return
            end
            append_chunk(data)
        end

        local stdio = { nil, stdout_pipe, stderr_pipe }
        local opts = { args = { "-c", command }, stdio = stdio }
        if cwd then opts.cwd = cwd end

        local handle, pid_or_err, name = uv.spawn("/bin/sh", opts, function(code, signal)
            exit_code = code
            exit_signal = signal
            pending_events = pending_events - 1
            -- The on-exit callback is responsible for closing the
            -- process handle, per luv convention.
            if process_handle and not process_handle:is_closing() then
                process_handle:close()
            end
            try_resume()
        end)

        if not handle then
            -- Spawn failed before we ever started — `pid_or_err` is
            -- the error message. Clean up pipes and return.
            spawn_error = tostring(pid_or_err) ..
                (name and (" (" .. name .. ")") or "")
            stdout_pipe:close(); stderr_pipe:close()
            return "Error: failed to spawn shell: " .. spawn_error
        end
        process_handle = handle

        stdout_pipe:read_start(on_read)
        stderr_pipe:read_start(on_read)

        -- Timeout timer. If it fires, we send SIGTERM and arm a
        -- second short timer to follow up with SIGKILL.
        timeout_timer = uv.new_timer()
        timeout_timer:start(timeout_ms, 0, function()
            timed_out = true
            if process_handle and not process_handle:is_closing() then
                process_handle:kill("sigterm")
            end
            timeout_timer:stop(); timeout_timer:close(); timeout_timer = nil
            kill_timer = uv.new_timer()
            kill_timer:start(SIGKILL_GRACE_MS, 0, function()
                if process_handle and not process_handle:is_closing() then
                    process_handle:kill("sigkill")
                end
                kill_timer:stop(); kill_timer:close(); kill_timer = nil
            end)
        end)

        -- Wait for stdout EOF, stderr EOF, and on_exit.
        coroutine.yield()

        -- Close pipes (idempotent if already closing).
        if not stdout_pipe:is_closing() then stdout_pipe:close() end
        if not stderr_pipe:is_closing() then stderr_pipe:close() end
        if spill_handle then uv.fs_close(spill_handle) end

        -- Build the result.
        local header
        if timed_out then
            header = string.format(
                "[shell] timed out after %ds; killed (exit code=%s signal=%s)",
                timeout_s, tostring(exit_code or "?"), tostring(exit_signal or "?")
            )
        elseif exit_signal and exit_signal ~= 0 then
            header = string.format(
                "[shell] terminated by signal %s (exit code=%s)",
                tostring(exit_signal), tostring(exit_code or "?")
            )
        else
            header = string.format("[shell] exit code %d", exit_code or -1)
        end

        local body = buffer_to_string()
        local parts = { header, "", body }
        if overflowed then
            if spill_path and not spill_error then
                parts[#parts + 1] = string.format(
                    "\n[truncated: kept last %d bytes; full %d-byte transcript " ..
                        "saved to %s. Use `read` with `start_line`/`end_line` " ..
                        "to inspect specific regions.]",
                    MAX_BYTES, total_written_to_spill, spill_path
                )
            else
                parts[#parts + 1] = string.format(
                    "\n[truncated: kept last %d bytes; could NOT spill to disk: %s]",
                    MAX_BYTES, spill_error or "unknown error"
                )
            end
        end
        return table.concat(parts, "\n")
    end,
}