terret-tools-std 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f478bf0ef01eea37428130547c4ac4f12c4eaa9748755fabc2ea50092995f313
+  data.tar.gz: 864c91ca3da1048139a7ec0393e5fb0b154221be7e95cb045d5815dd4e28cec5
+SHA512:
+  metadata.gz: 9271fb5ad1490767a32d3fcc2d39c73535aee8ee4e1f15ab18ce81d79ab4d7ebed14474ad3e16f44f8e342e66d458a7b5dcebd06a313e2ce3897f2eadaf4d9b7
+  data.tar.gz: 23e18fdeb8810c78eb0614b2a096d00f72016772740ed34f4c7da76939393cfa5fb56a210b7e48e38fbb4041bd19752f34f4589f7d0fb3ca7912a6255224e275

data/lib/terret/tools_std/bash.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Terret
+  module ToolsStd
+    # `Bash` (docs/exec.md §5) — Claude Code's name over ctx[:shell]'s
+    # persistent per-session bash.
+    #
+    # Two things here are more than delegation. The first is approval. §13:
+    # outside a sandbox an agent that can run arbitrary shell commands needs
+    # a human every time; inside one the container is already the backstop
+    # and Bash is governed like any other mutating tool. That verdict is
+    # derived when the tool is REGISTERED and lives in a Definition nobody
+    # re-reads, so a hot sandbox swap would otherwise leave a stale value in
+    # front of a shell whose isolation had changed underneath it — which is
+    # what the config/updated listener below exists for.
+    #
+    # The second is what the seam hands back. Shell::Result carries facts the
+    # caller never asked for — the session restarted, output was dropped — in
+    # a `notice` field of its own, precisely so stdout stays exactly what the
+    # terminal carried. A tool rendering stdout alone would silently swallow
+    # both, so the notice is reported below a separator, where a model can
+    # tell it from something the command itself printed.
+    class Bash < Hames::Service
+      service_key :tools_std_bash
+      inject :tools, :shell, :sandbox
+      config_schema max_output: { type: Integer, default: 30_000,
+                                  doc: "bytes of Bash output returned to the model before truncation" }
+
+      # What one result may show. The seam has its own cap
+      # (Shell::DEFAULT_MAX_OUTPUT, a mebibyte) and it is a memory bound;
+      # this one is a display decision, the tool's own honest cap rather than
+      # policy's — a truncator listening on tools/post_execute is free to cut
+      # further, and this is what the model sees when none does.
+      DEFAULT_MAX_OUTPUT = 30_000
+
+      # The line between the command's bytes and this file's remarks. It is a
+      # fixed literal in a stream a command controls, so a command CAN print
+      # it — this is a readability device, not a security boundary, and it is
+      # not claimed as one. What it does deliver is that the genuine remarks
+      # are always the last thing in the result, appended after anything a
+      # command forged, and that the remarks are advisory data rather than
+      # instructions (docs/security.md): nothing downstream acts on them, so
+      # a forged line buys a confusing result and no authority.
+      LEDGER = "--- terret ---"
+
+      DESCRIPTION = "Run a command in this session's persistent bash. The same shell process " \
+                    "serves every call in a session, so state persists: a `cd` or an `export` " \
+                    "from one call is still in effect on the next. A command that hits its " \
+                    "timeout is interrupted and its shell replaced, which resets the working " \
+                    "directory and every variable — the result says so when that happens."
+
+      def start(ctx)
+        @ctx = ctx
+        # One effect frame, owned by this row (start runs under the loader's
+        # with_owner), disposing whichever registration is current. The
+        # indirection is load-bearing: the loader emits config/updated
+        # OUTSIDE with_owner, so a registration made from the listener below
+        # belongs to no row at all — and an ownerless Bash would outlive the
+        # row that mounted it, leaving a tool holding shell authority that
+        # unloading the plugin could no longer take away.
+        @ctx.effect do
+          register_bash
+          -> { @registration&.call }
+        end
+
+        # Which row carries the sandbox knob is not this service's business —
+        # it may be the sandbox row's own config, or a provider reading
+        # someone else's — so the verdict is re-derived on any row's swap
+        # rather than an id being guessed, and the tool is rebuilt only when
+        # the answer actually moved.
+        #
+        # A provider whose `isolated?` raises during that re-derivation is
+        # isolated by the bus (listener errors do not escape an emit), which
+        # leaves the PREVIOUS approval standing rather than a wrong one.
+        # That is the safe direction while `:policy` on a mutating tool and
+        # `:always` park identically (docs/exec.md §5), and it becomes
+        # load-bearing the day a consumer tells those two apart.
+        @ctx.on("config/updated") { |_id, _config| refresh! }
+      end
+
+      # max_output is read at call time, so a swapped row governs the very
+      # next call with nothing to re-derive here. The approval IS a
+      # registration-time capture — the listener above, not a remount, is
+      # what keeps it current.
+      def reconfigure(_config); end
+
+      private
+
+      # `ctx:` is passed explicitly: the registry would otherwise record the
+      # frame on the context it was started in (the root), so a roster
+      # mounted into a forked agent scope would leave registrations behind
+      # that outlive the fork — a disposed agent with a tool of its own that
+      # still holds shell authority.
+      def tool(name, description, params, mutating:, approval:, concurrency:, &handler)
+        @ctx[:tools].register(name: name, description: description, params: params,
+                              mutating: mutating, approval: approval,
+                              concurrency: concurrency, ctx: @ctx, &handler)
+      end
+
+      def register_bash
+        @approval = derive_approval
+        params = {
+          type: "object",
+          properties: {
+            command: { type: "string", description: "The command to run in this session's bash" },
+            timeout: { type: "integer",
+                       description: "Optional timeout in milliseconds; the shell session is " \
+                                    "replaced if it fires" }
+          },
+          required: ["command"]
+        }
+        @registration = tool("Bash", DESCRIPTION, params, mutating: true, approval: @approval,
+                             concurrency: :serial) do |command:, session_id:, timeout: nil|
+          # session_id is the executing call's, handed to handlers that ask
+          # for it (Tools::Registry#handler_args). It is what keeps one
+          # agent's cwd and exported variables out of another's shell.
+          render(@ctx[:shell].run(command, session: session_id, timeout: seconds(timeout)))
+        end
+      end
+
+      # §13. The sandbox's own verdict, never a config knob of this row's:
+      # an isolation claim belongs to the thing doing the isolating.
+      def derive_approval = @ctx[:sandbox].isolated? ? :policy : :always
+
+      def refresh!
+        return if derive_approval == @approval
+
+        @registration&.call
+        register_bash
+      end
+
+      # Claude Code's Bash takes its timeout in milliseconds and this seam
+      # takes seconds. Keeping CC's units in the argument (a model that has
+      # written this call before writes milliseconds) puts the conversion
+      # here, in one line, instead of leaving a units mismatch in the wild.
+      #
+      # Both branches below are about arguments a model actually writes.
+      # `"500"` is JSON it typed, so Integer() accepts the string forms and
+      # refuses the rest with a sentence rather than a NoMethodError. A zero
+      # or negative timeout falls back to the seam's default instead of
+      # firing at once: an immediate timeout would interrupt the command and
+      # kill the shell, so a model's own bad argument would cost it the cwd
+      # and variables it had built up — damage to the caller, from the
+      # caller, reported as a timeout nobody asked for.
+      def seconds(ms)
+        return nil if ms.nil?
+
+        ms = begin
+          Integer(ms)
+        rescue TypeError, ArgumentError
+          raise Terret::Tools::Failure, "timeout must be a whole number of milliseconds"
+        end
+        ms.positive? ? ms / 1000.0 : nil
+      end
+
+      # Clamped rather than trusted: a row carrying a negative cap would
+      # otherwise byteslice its way to nil and raise on every single call,
+      # turning one bad config value into a tool that never works. Zero is
+      # then an honest answer — the result says it kept nothing and how much
+      # it dropped, which is visible in the very next tool result instead of
+      # in a crash a turn later.
+      def max_output = [config[:max_output] || DEFAULT_MAX_OUTPUT, 0].max
+
+      def render(result)
+        body, dropped = cap(scrub(result.stdout))
+        remarks = remarks_for(result, body, dropped)
+        return body.empty? ? "(no output)" : body if remarks.empty?
+
+        # The command's own bytes are never rewritten: the newline below only
+        # puts the separator on a line of its own, and output that already
+        # ended in one simply gets a blank line before the ledger.
+        "#{body.empty? ? '' : "#{body}\n"}#{LEDGER}\n#{remarks.join("\n")}"
+      end
+
+      def remarks_for(result, body, dropped)
+        remarks = []
+        # A zero status is the silent case — announcing success on every call
+        # would be noise in every result a model reads. A nil status is not
+        # silent by luck: the only two paths that produce one (an interrupted
+        # command, a shell that ended) always carry a notice explaining it.
+        remarks << "exit status #{result.status}" if result.status && !result.status.zero?
+        # Both counts measure the RENDERED text — what a model would have
+        # been shown — not the command's raw bytes. Two things separate the
+        # two: scrubbing has already replaced anything that was not valid
+        # UTF-8 (a replacement character is three bytes where the original
+        # may have been one), and the seam's own megabyte cap may have
+        # dropped output before this one ever saw it, reporting that
+        # separately in the notice. Saying "of rendered output" is what keeps
+        # this line from implying it counted what the command wrote.
+        if dropped.positive?
+          remarks << "output truncated at max_output: kept the first #{body.bytesize} bytes " \
+                     "of rendered output and dropped #{dropped} more"
+        end
+        remarks << "notice: #{result.notice}" if result.notice
+        remarks
+      end
+
+      # Child bytes are not guaranteed to be text. The seam preserves
+      # whatever the command wrote (that is its job) and the session log
+      # refuses invalid UTF-8 at the durable append boundary, so this is the
+      # layer where they have to become storable — replacing what was never
+      # valid rather than dropping the whole result on the floor.
+      def scrub(stdout) = stdout.to_s.scrub
+
+      def cap(text)
+        limit = max_output
+        return [text, 0] if text.bytesize <= limit
+
+        kept = whole_characters(text.byteslice(0, limit))
+        [kept, text.bytesize - kept.bytesize]
+      end
+
+      # Cutting at a byte offset can split a character in half, and those
+      # halves are bytes this file manufactured — the child never wrote them,
+      # and a durable append JSON-encodes the payload, so a manufactured half
+      # raises a layer away from the code that broke it. At most three bytes
+      # come back off, the longest tail a split UTF-8 character can leave.
+      # Belt and braces after #scrub, and kept anyway: the same rule the seam
+      # holds itself to (Shell#whole_characters), for the same reason.
+      def whole_characters(text)
+        text = text.byteslice(0, text.bytesize - 1) until text.valid_encoding?
+        text
+      end
+    end
+  end
+end

data/lib/terret/tools_std/files.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module Terret
+  module ToolsStd
+    # The standard file roster (docs/exec.md §5), carrying Claude Code's tool
+    # names verbatim because orchestrator allow lists are already written
+    # against those exact strings and `File.fnmatch` patterns have hardened
+    # around them — a Terret-native name would buy nothing but a permanent
+    # translation layer.
+    #
+    # Every handler reaches the filesystem through ctx[:fs] and nothing else.
+    # That is what makes the roster portable across the sandbox seam: when a
+    # config row swaps the sandbox provider (plan §12), these tools move with
+    # it untouched, because they never learned where the bytes actually live.
+    class Files < Hames::Service
+      service_key :tools_std_files
+      inject :tools, :fs
+      config_schema rg: { type: [TrueClass, FalseClass], default: true,
+                          doc: "use ripgrep for Grep when it and a subprocess seam are available" }
+
+      DEFAULT_GLOB = "**/*"
+
+      # A grep that never returns is a turn that never ends.
+      RG_TIMEOUT = 30
+
+      # ripgrep takes its search paths as argv, and a large workspace can
+      # exceed the kernel's argv limit. Past this budget the scan stays
+      # in-process rather than risking Errno::E2BIG.
+      MAX_RG_ARGV_BYTES = 100_000
+
+      def start(ctx)
+        @ctx = ctx
+        register_read
+        register_write
+        register_edit
+        register_glob
+        register_grep
+      end
+
+      # start captures nothing from config: `rg` is read at call time, so a
+      # swapped row governs the very next Grep and there is nothing here to
+      # re-derive. Saying so explicitly beats letting the base class warn that
+      # this service needs a remount when it does not.
+      def reconfigure(_config); end
+
+      private
+
+      # `ctx:` is passed explicitly on every registration. The registry
+      # defaults it to the context IT was started in, which is the root — so a
+      # roster mounted into a forked agent scope would leave its registration
+      # frames on the root context, outliving the fork that made them. Handing
+      # register the ctx this service was started in puts each frame where
+      # this row's lifetime is: unload the row, or dispose the fork it was
+      # mounted into, and the tools go with it. That is what stands between a
+      # disposed agent and a tool of its own that still holds filesystem
+      # authority.
+      def tool(name, description, params, mutating:, approval:, concurrency:, &handler)
+        @ctx[:tools].register(name: name, description: description, params: params,
+                              mutating: mutating, approval: approval,
+                              concurrency: concurrency, ctx: @ctx, &handler)
+      end
+
+      def object_schema(properties, required)
+        { type: "object", properties: properties, required: required }
+      end
+
+      def path_property(purpose)
+        { type: "string", description: "Absolute path to #{purpose}, inside the granted workspace" }
+      end
+
+      def register_read
+        tool("Read", "Read a file's full contents.",
+             object_schema({ file_path: path_property("the file to read") }, ["file_path"]),
+             mutating: false, approval: :never, concurrency: :parallel) do |file_path:|
+          @ctx[:fs].read(file_path)
+        end
+      end
+
+      def register_write
+        params = object_schema(
+          { file_path: path_property("the file to write"),
+            content: { type: "string", description: "The file's full new contents" } },
+          %w[file_path content]
+        )
+        tool("Write", "Write a file, replacing it if it exists and creating parent directories as needed.",
+             params, mutating: true, approval: :policy, concurrency: :serial) do |file_path:, content:|
+          "Wrote #{content.to_s.bytesize} bytes to #{@ctx[:fs].write(file_path, content)}"
+        end
+      end
+
+      def register_edit
+        params = object_schema(
+          { file_path: path_property("the file to edit"),
+            old_string: { type: "string", description: "Exact text to replace; must appear exactly once" },
+            new_string: { type: "string", description: "Text to put in its place" } },
+          %w[file_path old_string new_string]
+        )
+        description = "Replace one exact occurrence of a string in a file. Refuses if it appears " \
+                      "zero times or more than once, so include enough surrounding text to make it unique."
+        tool("Edit", description, params,
+             mutating: true, approval: :policy, concurrency: :serial) do |file_path:, old_string:, new_string:|
+          "Edited #{@ctx[:fs].edit(file_path, old_string, new_string)}"
+        end
+      end
+
+      def register_glob
+        params = object_schema(
+          { pattern: { type: "string", description: "Glob pattern, e.g. **/*.rb, matched in every workspace root" } },
+          ["pattern"]
+        )
+        tool("Glob", "List workspace files matching a glob pattern, as absolute paths.",
+             params, mutating: false, approval: :never, concurrency: :parallel) do |pattern:|
+          listing(@ctx[:fs].glob(pattern), "No files matched")
+        end
+      end
+
+      def register_grep
+        params = object_schema(
+          { pattern: { type: "string", description: "Regular expression to search for" },
+            glob: { type: "string", description: "Glob limiting which files are searched (default #{DEFAULT_GLOB})" } },
+          ["pattern"]
+        )
+        tool("Grep", "Search workspace file contents for a regular expression. Returns matching lines as " \
+                     "absolute_path:line_number:line.",
+             params, mutating: false, approval: :never, concurrency: :parallel) do |pattern:, glob: DEFAULT_GLOB|
+          grep(pattern, glob)
+        end
+      end
+
+      def listing(paths, empty_message) = paths.empty? ? empty_message : paths.join("\n")
+
+      def grep(pattern, glob)
+        files = searchable(glob)
+        return "No matches" if files.empty?
+
+        lines = (ripgrep(pattern, files) if use_rg?(files)) || scan(pattern, files)
+        listing(lines, "No matches")
+      end
+
+      # Directories are dropped through the same seam that produced the
+      # listing rather than with a bare File.directory?: every path this tool
+      # touches passes ctx[:fs], so containment and the fs/authorize
+      # waterfall see all of it and not just the reads.
+      def searchable(glob)
+        @ctx[:fs].glob(glob).reject { |p| @ctx[:fs].stat(p)[:directory] }
+      end
+
+      def use_rg?(files)
+        config.fetch(:rg, true) && @ctx.service?(:subprocess) &&
+          files.sum { |f| f.bytesize + 1 } <= MAX_RG_ARGV_BYTES && rg_on_path?
+      end
+
+      # PATH is this process's own environment, not workspace content, so it
+      # is read directly — routing it through ctx[:fs] would (correctly) deny
+      # every directory on it.
+      def rg_on_path?
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+          exe = File.join(dir, "rg")
+          File.file?(exe) && File.executable?(exe)
+        end
+      end
+
+      # ripgrep is a fast path, never a different answer: it is handed exactly
+      # the file list the in-process scan would have walked, so the two paths
+      # agree on which files are searched and differ only in regex dialect.
+      # It runs through ctx[:subprocess] like every other spawn in Terret,
+      # which is what keeps it inside the sandbox once one is mounted.
+      #
+      # Returns nil when ripgrep proved unusable and the caller should scan
+      # in-process instead. There are two ways that happens, because
+      # rg_on_path? only ever probed THIS process's PATH and the spawn's own
+      # verdict outranks it: a local spawn that cannot find the binary raises
+      # Errno::ENOENT, while a sandbox running the argv somewhere else answers
+      # with a status and never raises — `docker exec` exits 127 for a command
+      # missing from the container, 126 for one that is there but not
+      # executable. A host with ripgrep and an image without it is the ordinary
+      # case, not an exotic one, so neither may fail the call.
+      def ripgrep(pattern, files)
+        # --no-ignore because which files get searched is ctx[:fs]'s decision,
+        # already made: the list below IS the answer, and a .gitignore in the
+        # workspace must not quietly shrink it out from under the in-process
+        # scan that knows nothing about ignore files.
+        argv = ["rg", "--line-number", "--no-heading", "--with-filename",
+                "--no-ignore", "--color", "never", "-e", pattern, *files]
+        # cwd is a workspace directory (files is non-empty here) so the
+        # sandboxed world always has one it can actually enter.
+        result = @ctx[:subprocess].spawn(argv, cwd: File.dirname(files.first), timeout: RG_TIMEOUT)
+        case result.status
+        when 0 then result.stdout.lines.map(&:chomp)
+        when 1 then [] # ripgrep's "no matches" — an answer, not a failure
+        when 126, 127 then nil # no usable rg where the argv actually ran
+        else
+          # A bad pattern is the caller's problem. Silently retrying it under
+          # Ruby's regex dialect would hide that the two engines disagree.
+          raise Terret::Tools::Failure, "ripgrep failed: #{failure_detail(result)}"
+        end
+      rescue Errno::ENOENT
+        nil # the local-spawn miss; the status branch above is the sandbox's
+      end
+
+      def failure_detail(result)
+        detail = result.stderr.to_s.strip
+        detail = result.stdout.to_s.strip if detail.empty?
+        detail.empty? ? "exit status #{result.status.inspect}" : detail
+      end
+
+      def scan(pattern, files)
+        rx = compile(pattern)
+        files.flat_map do |path|
+          body = @ctx[:fs].read(path)
+          # Matching a Regexp against invalid UTF-8 raises, and a binary file
+          # is not a grep target anyway; ripgrep skips them too, so skipping
+          # here keeps the two paths agreeing on the same set of files.
+          next [] unless body.valid_encoding?
+
+          body.each_line.with_index(1).filter_map do |line, n|
+            "#{path}:#{n}:#{line.chomp}" if rx.match?(line)
+          end
+        end
+      end
+
+      def compile(pattern)
+        Regexp.new(pattern)
+      rescue RegexpError => e
+        raise Terret::Tools::Failure, "bad search pattern: #{e.message}"
+      end
+    end
+  end
+end