terret 0.0.2 → 0.1.0

data/lib/terret/doctor.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative "composition"
+
+module Terret
+  # `trt doctor` resolves a profile and validates every row's config against its
+  # plugin's Hames::Schema, without booting anything (docs/composition.md §9).
+  #
+  # It requires the composition's code and materializes each row (so !env,
+  # !setting and !ruby resolve to concrete values), then maps each row's plugin
+  # to its class and checks the materialized config against the class's schema.
+  # Nothing is mounted: doctor reports on a composition it never boots.
+  #
+  # Two semantics keep the exit status trustworthy, and both err the same way:
+  # a service with no schema is reported `unschema'd`, not failed, and an extra
+  # key WARNS rather than fails. Environment probes — does OPENROUTER_API_KEY
+  # resolve — print as informational lines and never as failures: doctor
+  # validates config, not the world. Exit status is 1 only when an enabled row's
+  # config is actually wrong.
+  module Doctor
+    # Returns a process exit status: 1 when an enabled row's config is wrong,
+    # 0 otherwise.
+    def self.run(resolved, allow_config_ruby: false, out:)
+      load_failures = require_code(resolved, allow_config_ruby)
+      # Settings resolve once, but a bad !setting/!ruby in settings: must not
+      # abort the whole run and hide the row table. It becomes its own error
+      # line; rows then materialize against empty settings, so any !setting in a
+      # row surfaces as that row's own error rather than a swallowed one.
+      settings, settings_error = begin
+        [Composition.materialize_settings(resolved.settings, allow_config_ruby: allow_config_ruby), nil]
+      rescue Composition::Error => e
+        [{}, e.message]
+      end
+      results = resolved.rows.map { |row| check(row, settings, allow_config_ruby) }
+
+      render(resolved, results, load_failures, settings_error, out)
+      bad = settings_error || results.any? { |r| !r[:disabled] && r[:status] == :error }
+      bad ? 1 : 0
+    end
+
+    # Requiring the composition's code, best-effort: a require that fails does
+    # not abort doctor. It surfaces as an info line for the file, and as the
+    # per-row "does not resolve" error for every class that file would define —
+    # which is more useful than a single aborted run.
+    #
+    # doctor is the SAFE preview — "validates config, not the world" — so a
+    # path-shaped require in a profile's plugins: (portable config from anywhere)
+    # is NOT executed to do that job: it surfaces as a load failure the same way
+    # a missing feature does, keeping `trt doctor <untrusted profile>` from being
+    # arbitrary code execution. A bundle's requires: ship inside an installed gem
+    # and are trusted (they may name a path to their own lib);
+    # --allow-config-ruby is the operator's consent to load a profile path too,
+    # exactly as at boot.
+    def self.require_code(resolved, allow_config_ruby)
+      refused, permitted = resolved.plugins.partition do |file|
+        !allow_config_ruby && !Composition.load_path_feature?(file)
+      end
+      failures = (resolved.requires + permitted).filter_map do |file|
+        require file
+        nil
+      rescue LoadError => e
+        [file, e.message]
+      end
+      failures + refused.map do |file|
+        [file, "refused: a filesystem path, not a load-path feature name; doctor does " \
+               "not execute untrusted requires — pass --allow-config-ruby to load it"]
+      end
+    end
+
+    # One row's verdict. The row id names the row in the table's first column,
+    # so validate is called WITHOUT a subject — the schema can name the row (its
+    # unit tests prove it), but here the column already does, and the doc's
+    # `error: sink must be a String` reads better without the id repeated.
+    def self.check(row, settings, allow_config_ruby)
+      base = { id: row.id, plugin: row.plugin, disabled: row.disabled }
+      config = Composition.materialize(row.config, settings: settings, allow_config_ruby: allow_config_ruby,
+                                                   where: "row #{row.id.inspect}")
+      klass = constantize(row.plugin)
+      return base.merge(status: :error, detail: "#{row.plugin} does not resolve to a plugin class") unless klass
+      unless plugin_class?(klass)
+        # A name that resolves to a live constant that is not a plugin (String, a
+        # module, a typo hitting something real) is not "a plugin with no schema"
+        # — it is a wrong plugin:, and reporting it unschema'd would hide that.
+        return base.merge(status: :error, detail: "#{row.plugin} is not a plugin " \
+                                                   "(its instances do not respond to #apply)")
+      end
+
+      schema = klass.respond_to?(:config_schema) ? klass.config_schema : nil
+      return base.merge(status: :unschema, detail: nil) unless schema
+
+      # redact: a value here is a materialized !env/!setting/!ruby result and
+      # may be a secret; the detail names its type only, never its content.
+      result = schema.validate(config, redact: true)
+      status = if result.errors.any? then :error
+               elsif result.warnings.any? then :warn
+               else :ok
+               end
+      base.merge(status: status, detail: (result.errors + result.warnings).join("; "))
+    rescue Composition::Error => e
+      # A row whose !setting or !ruby cannot resolve is a config fault doctor
+      # owns, reported against the row rather than crashing every other row.
+      base.merge(status: :error, detail: e.message)
+    end
+
+    def self.constantize(name)
+      Object.const_get(name)
+    rescue NameError
+      nil
+    end
+
+    # The plugin contract boot itself enforces (boot.rb): a class whose instances
+    # respond to #apply. Using the same test keeps doctor from red-flagging a
+    # composition boot would accept — including a third-party functional plugin
+    # that is not a Hames::Service.
+    def self.plugin_class?(klass)
+      klass.is_a?(Class) && klass.method_defined?(:apply)
+    end
+
+    # -- output ----------------------------------------------------------------
+
+    def self.render(resolved, results, load_failures, settings_error, out)
+      out.puts "# doctor: profile #{resolved.profile.inspect}"
+      out.puts
+      if settings_error
+        out.puts "error  #{Composition.one_line(settings_error)}"
+        out.puts
+      end
+
+      # Row ids are validated at resolution, but plugin names, error details,
+      # env markers and file paths are not — a newline in any of them could
+      # forge a table row, so every printed value goes through one_line. Widths
+      # are computed on the neutralized plugin so the table stays aligned.
+      plugins = results.to_h { |r| [r[:id], Composition.one_line(r[:plugin])] }
+      row_w = [results.map { |r| r[:id].length }.max || 3, 3].max
+      plugin_w = [plugins.values.map(&:length).max || 6, 6].max
+      out.puts "#{'row'.ljust(row_w)}  #{'plugin'.ljust(plugin_w)}  status"
+      results.each do |r|
+        out.puts "#{r[:id].ljust(row_w)}  #{plugins[r[:id]].ljust(plugin_w)}  #{status_text(r)}"
+      end
+
+      info = info_lines(resolved, load_failures)
+      return if info.empty?
+
+      out.puts
+      info.each { |line| out.puts "info  #{Composition.one_line(line)}" }
+    end
+
+    def self.status_text(result)
+      detail = Composition.one_line(result[:detail].to_s)
+      text = case result[:status]
+             when :ok then "ok"
+             when :unschema then "unschema'd"
+             when :warn then "warn: #{detail}"
+             when :error then "error: #{detail}"
+             end
+      result[:disabled] ? "#{text}  (disabled)" : text
+    end
+
+    # Informational, never a verdict: which !env markers this composition reads
+    # and whether each resolves, plus any code that would not load. The resolved
+    # value of a marker never appears — a doctor that printed a secret would be
+    # one nobody could run in front of other people.
+    def self.info_lines(resolved, load_failures)
+      lines = env_markers(resolved.rows).map { |name| "#{name}: #{ENV.key?(name) ? 'set' : 'unset'}" }
+      load_failures.each { |file, message| lines << "could not require #{file.inspect}: #{message}" }
+      lines
+    end
+
+    def self.env_markers(rows)
+      names = []
+      rows.each { |row| collect_env(row.config, names) }
+      names.uniq
+    end
+
+    def self.collect_env(value, names)
+      case value
+      when Composition::Tagged then names << value.argument if value.tag == "env"
+      when Hash then value.each_value { |v| collect_env(v, names) }
+      when Array then value.each { |v| collect_env(v, names) }
+      end
+    end
+  end
+end

data/lib/terret/home.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Terret
+  # Terret home: where profiles live (docs/composition.md §3).
+  #
+  #   ~/.terret/
+  #   ├── patch.yml                  # applies to every profile
+  #   └── profiles/<name>/{profile.yml,patch.yml}
+  #
+  # TERRET_HOME overrides ~/.terret wholesale, which is what makes the layer
+  # stack testable — every composition test points it at a tmpdir — and what
+  # lets a deployment ship a home directory as an artifact rather than as
+  # instructions for populating a user's dotfiles.
+  #
+  # A home that does not hold the named profile falls back to the templates
+  # this gem ships (gems/terret/profiles), so `trt boot --profile headless`
+  # works on a machine whose home is empty. The home always wins where it has
+  # an opinion; the shipped templates are only the floor.
+  class Home
+    DEFAULT = "~/.terret"
+    SHIPPED = File.expand_path("../../profiles", __dir__)
+
+    # ENV is read here rather than at load time so a test can set TERRET_HOME
+    # after this file is required.
+    def self.resolve(path = nil)
+      return path if path.is_a?(Home)
+
+      env = ENV["TERRET_HOME"]
+      env = nil if env.nil? || env.empty?
+      new(path || env || DEFAULT)
+    end
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = File.expand_path(path.to_s)
+    end
+
+    def patch = File.join(path, "patch.yml")
+    def profile_dir(name) = File.join(path, "profiles", name.to_s)
+    def profile_config(name) = File.join(profile_dir(name), "profile.yml")
+    def profile_patch(name) = File.join(profile_dir(name), "patch.yml")
+
+    def shipped_profile_dir(name) = File.join(SHIPPED, name.to_s)
+    def shipped_profile_config(name) = File.join(shipped_profile_dir(name), "profile.yml")
+    def shipped_profile_patch(name) = File.join(shipped_profile_dir(name), "patch.yml")
+
+    # The pair of files a profile resolves to, home first and the shipped
+    # template as the floor. Either may be nil; a profile with neither does
+    # not exist.
+    #
+    # The two files are found independently on purpose. A home holding only a
+    # patch.yml is an operator who edited the one file the template told them
+    # to edit, and tying the patch's fate to a sibling profile.yml would drop
+    # it in silence — including when what it drops is a tightening of policy.
+    def profile_files(name)
+      config = [profile_config(name), shipped_profile_config(name)].find { |f| File.file?(f) }
+      shipped = config && config == shipped_profile_config(name)
+      patch = [profile_patch(name), (shipped_profile_patch(name) if shipped)]
+              .compact.find { |f| File.file?(f) }
+      [config, patch]
+    end
+
+    # Profile names offered by this home and by the shipped templates.
+    def profile_names
+      [File.join(path, "profiles"), SHIPPED]
+        .flat_map { |d| Dir.glob(File.join(d, "*", "profile.yml")) }
+        .map { |f| File.basename(File.dirname(f)) }
+        .uniq.sort
+    end
+
+    # dump-config prints these, so they are home-relative rather than absolute:
+    # a command whose whole purpose is "show me my config" should be safe to
+    # paste into an issue, and an absolute path names the operator.
+    def label(file)
+      f = file.to_s
+      return f.delete_prefix("#{path}/") if f.start_with?("#{path}/")
+      return "terret:#{f.delete_prefix("#{SHIPPED}/")}" if f.start_with?("#{SHIPPED}/")
+
+      f
+    end
+
+    def to_s = path
+  end
+end

data/lib/terret/schema_gems.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Terret
+  # Every gem whose services declare a Hames::Schema, as require paths. This is
+  # the single source `rake config:catalog` and the schema tests both read, so a
+  # newly configurable gem is added in one place. Split across two lists, a gem
+  # added to only one would be silently absent from the catalog with CI green.
+  #
+  # It is the base bundle's own requires plus the interface/adapter gems that
+  # ship schemas but are not part of terret-base (ws, mcp, morph).
+  SCHEMA_GEMS = %w[
+    terret/store/sqlite
+    terret/openrouter
+    terret/exec
+    terret/tools_std
+    terret/sandbox/docker
+    terret/ws
+    terret/acp
+    terret/mcp
+    terret/morph
+  ].freeze
+end

data/lib/terret/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Terret
+  # The meta-gem's own version — what `trt --version` prints and what
+  # terret.gemspec reads, so the number lives in exactly one place.
+  #
+  # Deliberately NOT Terret::VERSION: terret-core already owns that constant
+  # and it is terret-core's number. The 0.1.0 lockstep release aligns the two
+  # numbers, but they stay distinct constants — quietly redefining a sibling
+  # gem's version constant is not a thing this gem gets to do.
+  module Meta
+    VERSION = "0.1.0"
+  end
+end

data/profiles/headless/patch.yml

@@ -0,0 +1,27 @@
+# Rows this profile changes about terret-base. Applied after every bundle in
+# the stack, before ~/.terret/patch.yml and before any --patch overlay.
+#
+# A patch targeting an existing id replaces that row's config WHOLESALE. It
+# never deep-merges. So a patch that repoints the model has to carry the api
+# key along with it, and `trt dump-config --profile headless` is how you see
+# what a row currently holds before you replace it.
+#
+# A row with an id that is not in the stack yet is an insertion, and it has to
+# say where it goes with `before:` or `after:` naming an existing row.
+
+rows: []
+# ---------------------------------------------------------------------------
+# UNCOMMENT TO RUN TOOLS DIRECTLY ON THIS HOST, UNSANDBOXED.
+#
+# Every Bash command, every spawned process, and every terminal this agent
+# opens runs as you, on your machine, with your network. A prompt-injected
+# instruction that reaches a tool call has nothing between it and the host but
+# the allow list. See docs/security.md.
+#
+# This comment block is not a security control. What it is, is the difference
+# between a decision made and a default inherited.
+# ---------------------------------------------------------------------------
+# rows:
+#   - id: sandbox
+#     plugin: Terret::Exec::SandboxNone
+#     config: {}

data/profiles/headless/profile.yml

@@ -0,0 +1,57 @@
+# The headless profile — the template Terret ships (docs/composition.md §3).
+#
+# Copy this directory to ~/.terret/profiles/<name>/ and edit it, or edit it in
+# place under ~/.terret/profiles/headless/. A home that holds no copy falls
+# back to this file, so `trt boot --profile headless` runs out of the box —
+# which also means an unedited profile has no workspace and can read nothing.
+#
+#   trt dump-config --profile headless    # what the stack actually resolves to
+#   trt doctor      --profile headless    # what does not fit
+#   trt boot        --profile headless    # run it
+
+bundles:
+  - terret # terret-base, always layer one
+
+# Out-of-tree requires for code that is not a bundle. Bundles pull in their
+# own gems; this is for a plugin you wrote and put on the load path yourself.
+plugins: []
+
+# The settings map has no schema of its own. Its whole job is to be the target
+# of !setting references, so a value used by three rows is written once.
+settings:
+  # EVERY FILESYSTEM TOOL IS CONTAINED TO THESE DIRECTORIES, and an empty list
+  # denies every file operation. That is the safe default and not a bug: there
+  # is no ungranted-but-permitted state. Add the absolute path of the project
+  # you want the agent to work in.
+  #
+  #   workspace:
+  #     - /Users/you/code/some-project
+  workspace: []
+
+  store:
+    # ------------------------------------------------------------------
+    # CHANGE THIS TO A DIRECTORY YOU OWN.
+    #
+    # The append-only session log. Everything the agent reads, says and
+    # does lands here in the clear — prompts, tool output, file contents.
+    # The default below is a placeholder that works on a laptop and is a
+    # poor choice anywhere else: /var/tmp is world-shared, and this exact
+    # path is predictable, so on a multi-user box another account can read
+    # your agent's whole history (and, if it gets there first, choose what
+    # your agent reads back). Point it inside your home or your Terret
+    # home, on a filesystem you can back up.
+    #
+    # Absolute paths only. A relative one resolves against whatever
+    # directory trt happened to be run from, which is rarely what you meant.
+    # ------------------------------------------------------------------
+    path: /var/tmp/terret/sessions.db
+
+  model:
+    # "provider/model". The provider is the adapter name a row registered;
+    # terret-base registers "openrouter", keyed from OPENROUTER_API_KEY.
+    main: openrouter/anthropic/claude-sonnet-4.5
+
+  sandbox:
+    # The container every spawned process runs inside. It needs whatever
+    # toolchain your agent's commands expect; the default is small on purpose.
+    image: ruby:slim

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: terret
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Obie Fernandez
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -23,16 +23,101 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
-description: Placeholder release. Terret is a Ruby-native, model-agnostic agent harness
-  where everything is a plugin. This meta-gem will carry the trt CLI, profiles, and
-  boot; none of that is written yet. The working code is in terret-core and hames.
+- !ruby/object:Gem::Dependency
+  name: terret-exec
+  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'
+- !ruby/object:Gem::Dependency
+  name: terret-openrouter
+  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'
+- !ruby/object:Gem::Dependency
+  name: terret-sandbox-docker
+  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'
+- !ruby/object:Gem::Dependency
+  name: terret-store-sqlite
+  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'
+- !ruby/object:Gem::Dependency
+  name: terret-tools-std
+  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: 'The meta-gem, and the way a Terret is composed. Bundles ship ordered
+  config rows, profiles stack bundles, patches adjust rows by id, and Terret.boot
+  hands the result to the Hames loader -- so which plugins run, in what order, with
+  what config is a question YAML answers rather than Ruby. Ships terret-base (the
+  log, the harness, the model seam, the execution world sandboxed with the network
+  denied, the standard tool roster, and a policy floor that starts closed), the headless
+  profile template, and trt: boot, dump-config, doctor.'
 email:
 - obiefernandez@gmail.com
-executables: []
+executables:
+- trt
 extensions: []
 extra_rdoc_files: []
 files:
+- config/bundle.yml
+- exe/trt
+- lib/terret/boot.rb
 - lib/terret/cli.rb
+- lib/terret/composition.rb
+- lib/terret/doctor.rb
+- lib/terret/home.rb
+- lib/terret/schema_gems.rb
+- lib/terret/version.rb
+- profiles/headless/patch.yml
+- profiles/headless/profile.yml
 homepage: https://terret.org
 licenses:
 - MIT
@@ -41,6 +126,7 @@ metadata:
   source_code_uri: https://github.com/terret-org/terret
   bug_tracker_uri: https://github.com/terret-org/terret/issues
   rubygems_mfa_required: 'true'
+  terret: config/bundle.yml
 rdoc_options: []
 require_paths:
 - lib
@@ -57,5 +143,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: Ruby-native, model-agnostic agent harness (name placeholder)
+summary: 'Ruby-native, model-agnostic agent harness: profiles, boot, and the trt CLI'
 test_files: []