terret-tools-std 0.1.0

data/lib/terret/tools_std/jobs.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Terret
+  module ToolsStd
+    # `job_start` / `job_collect` / `job_stop` (docs/subagents.md §6) — work
+    # that outlives the tool call that started it, over ctx[:jobs]. snake_case
+    # because these three have no Claude Code equivalent to be verbatim with,
+    # the same rule that produced `terminal_*` in M7.
+    #
+    # The split in the metadata is the whole design in one table. Starting and
+    # stopping put a process into the world or take one out of it, so both are
+    # mutating and both are governed by policy; collecting reads a buffer and
+    # asks nobody. That is what lets a delegated agent watch a job it could
+    # never have started: a subagent's approval can never be answered
+    # (docs/subagents.md §2), so a `:policy` call from one is denied, while
+    # `job_collect` runs for anybody.
+    #
+    # Neither `cwd` nor `env` is a tool argument, for the reason the terminal
+    # tools give: a cwd the model chose is contained by nothing, and an env it
+    # writes is a place for a credential to be laundered into a child process.
+    # Both stay the row's decision, where a deployment can see them.
+    class Jobs < Hames::Service
+      service_key :tools_std_jobs
+      inject :tools, :jobs, :sandbox
+      config_schema max_output: { type: Integer, default: 30_000,
+                                  doc: "bytes of collected job output returned to the model before truncation" }
+
+      # The same literal Bash, WebFetch and Task separate their output with,
+      # and it carries the same caveats: a readability device rather than a
+      # security boundary — a job can print the line itself — whose actual
+      # delivery is that the genuine remarks are always last and always
+      # advisory data that nothing downstream acts on.
+      LEDGER = "--- terret ---"
+
+      # What one collect may show. The seam has its own cap
+      # (Jobs::DEFAULT_MAX_OUTPUT, a mebibyte) and that one is a memory bound;
+      # this is a display decision, the tool's own honest cap, exactly as
+      # Bash's is.
+      DEFAULT_MAX_OUTPUT = 30_000
+
+      START_DESCRIPTION =
+        "Start a shell command in the background and get back a job id. The command keeps " \
+        "running after this call returns and after the turn that started it ends; read what " \
+        "it has written with job_collect, and end it with job_stop. Each job is a fresh " \
+        "shell, not this session's persistent bash, so a `cd` or an `export` from a Bash " \
+        "call is not in effect here. A job does not survive a restart of the harness. If " \
+        "this call is interrupted before its result is recorded, a resume of the turn runs " \
+        "it again and starts a SECOND job — the first may still be running, with output " \
+        "nobody will collect — so after a resume, use job_collect to check for two ids " \
+        "where you expected one."
+
+      COLLECT_DESCRIPTION =
+        "Read whatever a job has written since the last time it was collected, and find out " \
+        "whether it is still running. The output is drained: the same bytes are never " \
+        "handed back twice, so keep what you are given."
+
+      STOP_DESCRIPTION =
+        "End a job: it is sent SIGTERM, then SIGKILL if it does not leave. Collect the job " \
+        "once more afterwards for anything it wrote on its way out."
+
+      def start(ctx)
+        @ctx = ctx
+        register_collect
+        register_stop
+        # job_start's approval is derived from sandbox isolation the way Bash's
+        # is (docs/exec.md §5, §13): job_start runs `bash -lc <cmd>` in a fresh
+        # shell, so unsandboxed it is arbitrary shell execution and needs a human
+        # every time, while inside a sandbox the container is the backstop and it
+        # is governed like any other mutating tool. The verdict is captured at
+        # registration, so a hot sandbox swap re-derives it through the
+        # config/updated listener rather than leaving a stale value in front of a
+        # shell whose isolation changed underneath it.
+        #
+        # The effect frame owns whichever registration is current: the loader
+        # emits config/updated OUTSIDE with_owner, so a registration made from
+        # the listener would belong to no row — and an ownerless job_start would
+        # outlive the row that mounted it, holding process-spawning authority
+        # nothing in the harness could still take away.
+        @ctx.effect do
+          register_start
+          -> { @start_registration&.call }
+        end
+        @ctx.on("config/updated") { |_id, _config| refresh_start! }
+      end
+
+      # max_output is read at call time, so a swapped row governs the very next
+      # call; every other knob these tools reach (the job cap, the cwd) belongs
+      # to the jobs row and is read there. job_start's approval, by contrast, IS
+      # a registration-time capture — the config/updated 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 can still spawn
+      # processes.
+      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 id_property
+        { type: "string", description: "The job id job_start handed back" }
+      end
+
+      def register_start
+        params = object_schema(
+          { command: { type: "string",
+                       description: "The shell command line to run in the background" } },
+          %w[command]
+        )
+        # `command` is required in the schema and defaulted here: a model that
+        # omits it has made a mistake, and an omitted keyword would cost a
+        # whole turn to an ArgumentError where a defaulted one costs a result
+        # the model can read and correct.
+        @start_approval = derive_approval
+        @start_registration = tool("job_start", START_DESCRIPTION, params, mutating: true,
+             approval: @start_approval, concurrency: :serial) do |session_id:, command: nil|
+          started(@ctx[:jobs].start(command!(command), session: session_id))
+        end
+      end
+
+      # §13 / docs/exec.md §5: 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_start!
+        return if derive_approval == @start_approval
+
+        @start_registration&.call
+        register_start
+      end
+
+      def register_collect
+        # :parallel because a collect is a read of a buffer with no ordering
+        # against its siblings — watching four jobs in one message is the case
+        # the barrier was declared for.
+        tool("job_collect", COLLECT_DESCRIPTION, object_schema({ id: id_property }, %w[id]),
+             mutating: false, approval: :never, concurrency: :parallel) do |session_id:, id: nil|
+          render(@ctx[:jobs].collect(id!(id, "job_collect"), session: session_id))
+        end
+      end
+
+      def register_stop
+        tool("job_stop", STOP_DESCRIPTION, object_schema({ id: id_property }, %w[id]),
+             mutating: true, approval: :policy, concurrency: :serial) do |session_id:, id: nil|
+          stopped(@ctx[:jobs].stop(id!(id, "job_stop"), session: session_id))
+        end
+      end
+
+      # Both refusals name the argument rather than the Ruby that would
+      # otherwise report it. An array here is a model reaching for the
+      # terminal_open convention, and stringifying it would start a job around
+      # a command nobody wrote.
+      def command!(command)
+        return command if command.is_a?(String) && !command.strip.empty?
+
+        raise Terret::Tools::Failure,
+              "job_start needs a command: one shell command line, as a string. Nothing " \
+              "was started."
+      end
+
+      def id!(id, tool)
+        return id if id.is_a?(String) && !id.strip.empty?
+
+        raise Terret::Tools::Failure,
+              "#{tool} needs the job id job_start handed back, as a string"
+      end
+
+      # The ledger line is what the model will address the job by for the rest
+      # of its life, so it is never omitted.
+      def started(id) = "The job is running in the background.\n#{LEDGER}\njob #{id}"
+
+      def stopped(id)
+        "Stopped job #{id}.\n#{LEDGER}\ncollect it once more for anything it wrote on its way out"
+      end
+
+      def render(result)
+        body, dropped = cap(scrub(result[:output]))
+        remarks = remarks_for(result, body, dropped)
+        "#{body.empty? ? '(no new output)' : body}\n#{LEDGER}\n#{remarks.join("\n")}"
+      end
+
+      # Unlike Bash's, the status remark is never silent. "Still running" and
+      # "finished" are the two facts a collect exists to establish, and a model
+      # left to infer them from an empty result will either poll a job that has
+      # been over for minutes or walk away from one that has not started
+      # writing yet.
+      def remarks_for(result, body, dropped)
+        remarks = [status_remark(result)]
+        # The dropped bytes are gone, not held back: this collect drained the
+        # buffer, so what did not fit the cap is not waiting for the next one.
+        # Saying "truncated" without saying that invites a model to collect
+        # again for the rest of a result nothing can hand it.
+        if dropped.positive?
+          remarks << "output truncated at max_output: kept the first #{body.bytesize} bytes " \
+                     "of rendered output and dropped #{dropped} more, which are gone rather " \
+                     "than waiting for the next collect"
+        end
+        # The seam's own cap, hit before this tool ever saw the bytes. Reported
+        # separately because it is a different loss: those bytes are gone from
+        # the buffer, not merely from this result.
+        if result[:truncated]
+          remarks << "some of the job's output was dropped before it could be collected; it " \
+                     "was writing faster than the buffer's cap allows"
+        end
+        remarks
+      end
+
+      def status_remark(result)
+        return "the job is still running" unless result[:status] == :exited
+        return "the job has exited with status #{result[:exit_status]}" if result[:exit_status]
+
+        "the job was stopped before it could report an exit status"
+      end
+
+      # Clamped rather than trusted: a row carrying a negative cap would
+      # otherwise byteslice its way to nil and raise on every call, turning one
+      # bad config value into a tool that never works.
+      def max_output = [config[:max_output] || DEFAULT_MAX_OUTPUT, 0].max
+
+      # A job's bytes are not guaranteed to be text. The seam preserves
+      # whatever the job 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.
+      def scrub(output) = output.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 — a durable append JSON-encodes
+      # the payload, so a manufactured half raises a layer away from the code
+      # that broke it. Belt and braces after #scrub, and kept anyway, for the
+      # same reason Bash keeps its copy.
+      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/task.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Terret
+  module ToolsStd
+    # `Task` (docs/subagents.md §4) — Claude Code's name verbatim, per the M7
+    # rule: allow lists in the wild are already written against `Task`, and a
+    # Terret-native name would buy a translation layer that does nothing but
+    # rename, forever. The tool is thin on purpose: it talks to
+    # `ctx[:subagents].run` and knows nothing else about what a subagent is.
+    #
+    # `approval: :never` on a tool that can obviously mutate the world is the
+    # one entry here that looks wrong and is not. The metadata describes what
+    # THIS call does directly, and this call starts a conversation. Everything
+    # the child then does passes the child's own pipeline: its own allow list,
+    # its own approvals gate, one decision per actual effect. Gating `Task`
+    # itself would ask a human to approve a call whose effects are not knowable
+    # until after the approval is granted — the worst possible moment to ask —
+    # and would then ask again, correctly, for each real effect inside.
+    #
+    # `concurrency: :parallel` because a Task call is a whole turn of latency,
+    # which is exactly the case the barrier was declared for.
+    class Task < Hames::Service
+      service_key :tools_std_task
+      inject :tools, :loop, :subagents
+      config_schema({}) # the Task tool takes no config (see the :subagents seam)
+
+      # The same literal Bash and WebFetch separate their output with, and it
+      # carries the same caveats: a readability device rather than a security
+      # boundary — a child could print the line itself — whose actual delivery
+      # is that the genuine remarks are always last and always advisory data
+      # that nothing downstream acts on.
+      LEDGER = "--- terret ---"
+
+      DESCRIPTION = "Delegate a whole task to a fresh subagent and get back its final answer. " \
+                    "The subagent starts with an empty conversation: the prompt is everything " \
+                    "it will see, so state the goal, the context it needs, and what to report " \
+                    "back. It runs with the same tools and the same permissions you have, and " \
+                    "its own work is logged in its own session rather than in yours."
+
+      def start(ctx)
+        @ctx = ctx
+        register_task
+      end
+
+      # Nothing is captured from config; there is no knob on this row.
+      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 a registration behind that
+      # outlives the fork.
+      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_task
+        params = {
+          type: "object",
+          properties: {
+            description: { type: "string",
+                           description: "A short label for the delegation, three to five words" },
+            prompt: { type: "string",
+                      description: "The subagent's whole instruction; it sees nothing else" }
+          },
+          required: %w[description prompt]
+        }
+        # Both are required in the schema and both are defaulted here. A
+        # delegation nobody can name is one nobody can follow, and a model
+        # writing one without a prompt has made a mistake — but an omitted
+        # keyword would cost a whole turn to an ArgumentError, where a
+        # defaulted one costs a result the model can read and correct.
+        # `description` is a label for a log or a UI line; the child never
+        # sees it, so nothing here uses it.
+        tool("Task", DESCRIPTION, params, mutating: false, approval: :never,
+             concurrency: :parallel) do |session_id:, description: nil, prompt: nil|
+          render(delegate(prompt, session_id))
+        end
+      end
+
+      # The load-bearing line of this tool. Task is registered on the ROOT
+      # context like the rest of the roster, so its closure captures the root
+      # and not any agent; what makes the child inherit the CALLER's roster and
+      # policy floor is looking the caller up here. `session_id` is injected by
+      # the registry and merged last, so a model that writes one into its
+      # arguments is naming somebody else's context and simply loses.
+      def delegate(prompt, session_id)
+        if prompt.nil? || (prompt.is_a?(String) && prompt.strip.empty?)
+          raise Terret::Tools::Failure,
+                "Task needs a prompt: it is everything the subagent will see. " \
+                "Nothing was delegated."
+        end
+        unless prompt.is_a?(String)
+          raise Terret::Tools::Failure,
+                "prompt must be a string; got #{prompt.class}. Nothing was delegated."
+        end
+
+        agent = @ctx[:loop].agent_for_session(session_id)
+        unless agent
+          raise Terret::Tools::Failure,
+                "no live agent owns this session, so Task has no context to delegate from"
+        end
+
+        @ctx[:subagents].run(prompt: prompt, ctx: agent.ctx)
+      end
+
+      # The ledger is not cosmetic and it is never omitted: nothing in the
+      # parent's log links it to the child's session except this line.
+      #
+      # A turn that did not complete is reported too. "Had nothing to say" and
+      # "was stopped part-way" are different facts about a delegation, and a
+      # model shown only the child's last sentence would summarize the second
+      # as if it were an answer.
+      def render(result)
+        text = result.text.to_s
+        remarks = ["child session #{result.session_id}"]
+        unless result.status == :completed
+          remarks << "the subagent's turn ended #{result.status} rather than completing"
+        end
+        "#{text.empty? ? '(no reply)' : text}\n#{LEDGER}\n#{remarks.join("\n")}"
+      end
+    end
+  end
+end

data/lib/terret/tools_std/terminals.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Terret
+  module ToolsStd
+    # `terminal_open` / `terminal_input` / `terminal_read` / `terminal_close`
+    # (docs/exec.md §5) — the four std tools with no Claude Code equivalent,
+    # over ctx[:terminals]'s named long-lived PTYs. A REPL or a dev server
+    # stays addressable across a whole turn, which is the difference between
+    # this seam and the one-shot spawn behind `Bash`.
+    #
+    # Every call passes its own session as the owner. Names are scoped per
+    # owner on the seam, so that argument is the whole reason one agent
+    # cannot read — or close — a live process belonging to another; a
+    # constant here would quietly merge every agent's terminals into the one
+    # namespace the seam was built to keep apart.
+    #
+    # Neither `cwd` nor `env` is a tool argument, deliberately. A terminal is
+    # spawned directly rather than through ctx[:fs], so nothing would contain
+    # a cwd the model chose, and an env the model writes is a place for a
+    # credential to be laundered into a child process. Both stay the row's
+    # decision, where a deployment can see them.
+    class Terminals < Hames::Service
+      service_key :tools_std_terminals
+      inject :tools, :terminals
+      config_schema({}) # the terminal tools take no config (see the :terminals seam)
+
+      def start(ctx)
+        @ctx = ctx
+        register_open
+        register_input
+        register_read
+        register_close
+      end
+
+      # Nothing is captured from config here: every knob these tools reach
+      # (the cap, the read timeout, the cwd) belongs to the terminals row and
+      # is read there, at call time. Saying so beats letting the base class
+      # warn that this row needs a remount when it does not.
+      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
+      # can still spawn processes.
+      # All four are `mutating: true`, `terminal_read` included, and that is
+      # not a rounding-up. Reading a PTY CONSUMES the stream: the bytes it
+      # returns are gone for every later read, so two identical calls give
+      # different answers and neither can be replayed. It is not reading in
+      # the sense the Read tool means, where the file is still there
+      # afterwards. The cost is that a deployment gating mutations asks about
+      # terminal_read too, which is the right trade — an approvals deployment
+      # is interactive by definition, and the alternative is a tool that
+      # quietly drains another tool's output while claiming to observe it.
+      def tool(name, description, params, &handler)
+        @ctx[:tools].register(name: name, description: description, params: params,
+                              mutating: true, approval: :policy, concurrency: :serial,
+                              ctx: @ctx, &handler)
+      end
+
+      def object_schema(properties, required)
+        { type: "object", properties: properties, required: required }
+      end
+
+      def name_property = { type: "string", description: "The terminal's name within this session" }
+
+      def register_open
+        params = object_schema(
+          { name: name_property,
+            argv: { type: "array", items: { type: "string" },
+                    description: "The command and its arguments, e.g. [\"python3\", \"-i\"]" } },
+          %w[name argv]
+        )
+        description = "Start a long-lived terminal (a PTY) that stays open across calls. No shell " \
+                      "interprets the argv, so use [\"bash\", \"-lc\", \"...\"] for pipelines or " \
+                      "redirection. The terminal keeps running until terminal_close."
+        tool("terminal_open", description, params) do |name:, argv:, session_id:|
+          open_terminal(name, argv!(argv), session_id)
+        end
+      end
+
+      def register_input
+        params = object_schema(
+          { name: name_property,
+            text: { type: "string",
+                    description: "Text to type; include a trailing newline to submit a line" } },
+          %w[name text]
+        )
+        tool("terminal_input", "Type text into an open terminal. Nothing is submitted until a " \
+                               "newline is sent, exactly as at a keyboard.", params) do |name:, text:, session_id:|
+          @ctx[:terminals].input(name, text, session: session_id)
+          "Typed #{text.to_s.bytesize} bytes into terminal #{name}"
+        end
+      end
+
+      def register_read
+        params = object_schema(
+          { name: name_property,
+            timeout: { type: "integer",
+                       description: "Optional milliseconds to wait for output before giving up" } },
+          %w[name]
+        )
+        tool("terminal_read", "Read whatever an open terminal has said since the last read. " \
+                              "Returns empty-handed rather than waiting for a terminal that has " \
+                              "nothing to say.", params) do |name:, session_id:, timeout: nil|
+          read_terminal(name, session_id, timeout)
+        end
+      end
+
+      def register_close
+        tool("terminal_close", "Close a terminal and reap its process, freeing the name.",
+             object_schema({ name: name_property }, %w[name])) do |name:, session_id:|
+          # The seam makes closing a name that is not open a no-op, because
+          # disposal runs over sets that may already be partly closed. The
+          # tool says which of the two happened rather than inventing a
+          # failure the seam deliberately does not raise.
+          if @ctx[:terminals].close(name, session: session_id).nil?
+            "No terminal named #{name} was open"
+          else
+            "Closed terminal #{name}"
+          end
+        end
+      end
+
+      # Named away from `open` and `read`: Kernel's own methods carry those
+      # names, and Kernel#open runs a command when handed a string starting
+      # with a pipe. A private helper that shadows it is one rename away from
+      # falling through to it, in the one class where that would hand a model
+      # a spawn nobody gated.
+      # argv arrives as whatever JSON the model wrote, and two shapes of it
+      # reach the kernel as something worse than an error. An empty list
+      # becomes a nil program and surfaces as "TypeError: no implicit
+      # conversion of nil into String" from inside exec; a nil element
+      # stringifies into an empty argument the kernel accepts happily, so the
+      # terminal opens around a command nobody wrote. Both are refused rather
+      # than repaired — repairing an argv is a guess about what the caller
+      # meant, made at the moment it is spawning a process.
+      def argv!(argv)
+        list = argv.is_a?(Array) ? argv : [argv]
+        raise Terret::Tools::Failure, "argv must name a command to run" if list.empty?
+
+        bad = list.reject { |arg| arg.is_a?(String) }
+        return list if bad.empty?
+
+        raise Terret::Tools::Failure,
+              "every argv element must be a string; got #{bad.first.inspect}"
+      end
+
+      def open_terminal(name, argv, session_id)
+        terminal = @ctx[:terminals].open(name, argv, session: session_id)
+        "Opened terminal #{terminal.name} (pid #{terminal.pid})"
+      rescue Errno::ENOENT
+        # The three errnos a spawn raises for an argv that cannot become a
+        # process. Left alone the pipeline renders Ruby's own wording, and
+        # EACCES's is actively misleading: "Permission denied - fork failed"
+        # names the one call that did NOT fail — the fork worked, the exec
+        # did not — so a model reads it as a broken harness and retries
+        # instead of fixing the argv it wrote. A Failure renders message-only,
+        # and the seam registers nothing before the spawn returns, so there is
+        # never a half-open terminal to mention.
+        #
+        # Deliberately not `SystemCallError`: EMFILE and ENFILE mean the
+        # harness is out of descriptors, which is not the caller's mistake to
+        # fix and must keep crashing loudly rather than being explained to a
+        # model as a bad command.
+        raise Terret::Tools::Failure,
+              "could not start #{argv.first.inspect}: no such command, or the terminal's " \
+              "working directory is gone; nothing was opened"
+      rescue Errno::EACCES, Errno::ENOEXEC
+        raise Terret::Tools::Failure,
+              "could not start #{argv.first.inspect}: not executable — a directory, or a file " \
+              "without the execute bit; nothing was opened"
+      end
+
+      def read_terminal(name, session_id, timeout)
+        chunk = @ctx[:terminals].read(name, session: session_id,
+                                            timeout: timeout.nil? ? nil : timeout / 1000.0)
+        # nil is the terminal's process being gone, "" is it being alive with
+        # nothing to say — two different answers, and a model that cannot
+        # tell them apart will either keep polling a dead terminal or close a
+        # live one. The name stays open in both cases; reading is not
+        # disposal.
+        return "(the terminal's process has ended; terminal_close frees the name)" if chunk.nil?
+        return "(nothing to read)" if chunk.empty?
+
+        # Same stance as Bash's: the seam preserves whatever the child wrote,
+        # the session log refuses invalid UTF-8 at the durable append
+        # boundary, so this is the layer that has to make it storable.
+        chunk.scrub
+      end
+    end
+  end
+end