terret-exec 0.1.0

data/lib/terret/exec/terminals.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Terret
+  module Exec
+    # This owner already holds `max_terminals` open. Refused rather than
+    # quietly reaping the oldest, or the dead ones: a terminal is a live
+    # process an agent asked to keep, and deciding on its behalf which one it
+    # has finished with is not ours to make. Closing one is the caller's move.
+    TerminalLimit = Class.new(Terret::Tools::Failure)
+
+    # No terminal by that name belongs to this owner — either it was never
+    # opened, it was closed, or it belongs to somebody else. All three are the
+    # same answer on purpose: which of them is true is not information one
+    # owner should be able to learn about another's terminals.
+    NoSuchTerminal = Class.new(Terret::Tools::Failure)
+
+    # The terminal is still registered, but the process behind it has exited.
+    # A typed refusal rather than a silent no-op, and rather than the raw
+    # Errno::EIO the pty master raises: the caller asked to type into
+    # something, nothing received it, and a model reading the result deserves
+    # a sentence naming the terminal instead of a device path. #read answers
+    # the same situation with nil, because "nothing to say" and "nothing left
+    # to say it" are the same shape to a reader.
+    TerminalGone = Class.new(Terret::Tools::Failure)
+
+    # A name this owner is already using. Opening over it would drop the
+    # handle to a running process — unreapable, since nothing would hold its
+    # pid any more — so the refusal is what keeps disposal honest.
+    TerminalExists = Class.new(Terret::Tools::Failure)
+
+    # ctx[:terminals] — named, long-lived PTYs (plan §6.6; docs/exec.md §2).
+    # They outlive a single tool call by design: a REPL or a dev server stays
+    # addressable across a turn, which is the whole difference between this
+    # seam and ctx[:subprocess]'s one-shot spawn.
+    #
+    # Names are scoped per owner, not global. `open(name, argv, session: key)`
+    # keys the registry on [owner, name], so two agents may each keep a
+    # terminal called "repl" without collision, and neither can address (or
+    # accidentally close) the other's by guessing its name — a terminal is a
+    # live process with the agent's authority, so a shared namespace would be a
+    # capability leak between agents, not merely a naming inconvenience.
+    # `close_all_for(key)` is then exactly "drop this owner's rows", which is
+    # what agent disposal needs. The cap counts per owner for the same reason:
+    # it is the limit an agent can see and act on, and its error message can
+    # say something true to the caller that hit it.
+    class Terminals < Hames::Service
+      service_key :terminals
+      inject :subprocess
+      config_schema max_terminals: { type: Integer, default: 8, doc: "cap on concurrently open terminals" },
+                    read_timeout:  { type: Numeric, default: 0.1,
+                                     doc: "seconds a non-blocking terminal read waits for output" },
+                    cwd:           { type: String,
+                                     doc: "default working directory for opened terminals (default: Dir.pwd)" }
+
+      # What `open` hands back. The handle itself stays in the registry: every
+      # other method is name-addressed, so nothing outside this service can
+      # drive a terminal around the cap or the ownership check.
+      Terminal = Data.define(:name, :owner, :pid)
+
+      DEFAULT_SESSION = :default
+      DEFAULT_MAX = 8
+      CHUNK = 4096
+
+      # Bounded, so reading a terminal that has nothing to say returns
+      # empty-handed instead of holding the turn open until it does.
+      DEFAULT_READ_TIMEOUT = 0.1
+
+      # Bounds the pre-close drain against a child writing without pause.
+      DRAIN_BUDGET = 0.1
+
+      def start(ctx)
+        @ctx = ctx
+        @open = {} # [owner, name] => PTYHandle
+        # Disposing the owning agent reaps every PTY it opened; fork disposal
+        # never touches this root-mounted state. Registered via ctx.on so it
+        # reverses when this service unloads.
+        ctx.on("agent/disposed") { |session_id| close_all_for(session_id) }
+      end
+
+      # The loader calls this on unload. Terminals are processes the harness
+      # owns; dropping the registry without reaping them would leak one per
+      # name for the life of the host process.
+      def stop(_ctx) = close_all
+
+      # Every knob is read where it is used, so a hot config swap needs nothing
+      # re-derived here — including a lowered `max_terminals`, which then bites
+      # on the next open rather than closing something already running.
+      def reconfigure(_config); end
+
+      def open(name, argv, session: DEFAULT_SESSION, cwd: nil, env: {})
+        name = name.to_s
+        owner = session.to_s
+        raise TerminalExists, "a terminal named #{name} is already open" if @open.key?([owner, name])
+
+        if (count = count_for(owner)) >= max
+          raise TerminalLimit, "#{count} terminals are already open; close one first (max_terminals: #{max})"
+        end
+
+        handle = @ctx[:subprocess].pty_spawn(argv, cwd: cwd || default_cwd, env: env)
+        @open[[owner, name]] = handle
+        Terminal.new(name: name, owner: owner, pid: handle.pid)
+      end
+
+      # The liveness check comes first because the write alone would not tell:
+      # Linux accepts a write to a pty master whose child is gone and quietly
+      # queues it, so only macOS would ever reach the rescue below. The rescue
+      # stays for the race the check cannot close — a child dying between the
+      # probe and the write, where macOS still raises.
+      def input(name, text, session: DEFAULT_SESSION)
+        handle = fetch(name, session)
+        unless handle.alive?
+          raise TerminalGone, "the terminal named #{name} has no live process; close it and open another"
+        end
+
+        handle.write(text)
+      rescue Errno::EIO, Errno::EPIPE, IOError
+        raise TerminalGone, "the terminal named #{name} has no live process; close it and open another"
+      end
+
+      # "" means the terminal is alive with nothing to say; nil means its child
+      # is gone. The entry survives that EOF — reading is not disposal, and the
+      # owner still has to close it, which is also what frees its slot.
+      def read(name, session: DEFAULT_SESSION, max: CHUNK, timeout: nil)
+        fetch(name, session).read(max, timeout: timeout || read_timeout)
+      end
+
+      # Reaps the child and forgets the name. Closing a name that is not open
+      # is a no-op rather than an error: disposal runs over sets that may
+      # already have been partly closed, and PTYHandle#close is itself
+      # idempotent.
+      def close(name, session: DEFAULT_SESSION)
+        handle = @open.delete([session.to_s, name.to_s]) or return nil
+        drain(handle)
+        handle.close
+      end
+
+      # The agent-disposal hook: everything this owner opened, closed and
+      # forgotten, by the names it used. Another owner's terminals are
+      # untouched.
+      def close_all_for(session)
+        owner = session.to_s
+        @open.keys.select { |(o, _n)| o == owner }.map do |(_o, name)|
+          close(name, session: owner)
+          name
+        end
+      end
+
+      def close_all = @open.keys.each { |(owner, name)| close(name, session: owner) }
+
+      private
+
+      def max = config[:max_terminals] || DEFAULT_MAX
+      def read_timeout = config[:read_timeout] || DEFAULT_READ_TIMEOUT
+      def default_cwd = config[:cwd] || Dir.pwd
+
+      def count_for(owner) = @open.keys.count { |(o, _n)| o == owner }
+
+      # Empty the terminal before the handle reaps its child. A process killed
+      # while its terminal still holds bytes nobody read can get stuck in exit
+      # — measured on macOS with a bash in the terminal, reliably, with as
+      # little as a startup banner pending — and the reaper's blocking wait
+      # would then never return. In the ordinary case this costs one
+      # non-blocking read; the budget bounds a child writing without pause.
+      def drain(handle)
+        deadline = monotonic + DRAIN_BUDGET
+        loop do
+          chunk = handle.read(CHUNK, timeout: 0)
+          return if chunk.nil? || chunk.empty? || monotonic >= deadline
+        end
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def fetch(name, session)
+        @open[[session.to_s, name.to_s]] or
+          raise NoSuchTerminal, "no terminal named #{name} is open"
+      end
+    end
+  end
+end

data/lib/terret/exec.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+begin
+  require "terret"
+rescue LoadError
+  require_relative "../../../terret-core/lib/terret" # monorepo path source
+end
+
+require_relative "exec/fs"
+require_relative "exec/sandbox_none"
+require_relative "exec/subprocess"
+require_relative "exec/shell"
+require_relative "exec/terminals"
+require_relative "exec/jobs"

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: terret-exec
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Obie Fernandez
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: terret-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: 'ctx[:fs]: workspace-contained file ops (read/write/edit/stat/glob) behind
+  an fs/authorize waterfall, with realpath-based containment that fails closed on
+  traversal and symlink escapes. ctx[:subprocess] spawns and captures under the fiber
+  scheduler with cooperative cancellation; ctx[:shell] keeps a bash per agent alive
+  across calls; ctx[:terminals] holds named long-lived PTYs; ctx[:jobs] runs a command
+  past the turn that started it; and every argv reaches a process through the ctx[:sandbox]
+  seam. Zero runtime dependencies beyond stdlib.'
+email:
+- obiefernandez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/terret/exec.rb
+- lib/terret/exec/fs.rb
+- lib/terret/exec/jobs.rb
+- lib/terret/exec/sandbox_none.rb
+- lib/terret/exec/shell.rb
+- lib/terret/exec/subprocess.rb
+- lib/terret/exec/terminals.rb
+homepage: https://terret.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://terret.org
+  source_code_uri: https://github.com/terret-org/terret
+  bug_tracker_uri: https://github.com/terret-org/terret/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'The execution-world gem for Terret: workspace-scoped filesystem and process
+  seams'
+test_files: []