terret-core 0.1.0 → 0.1.1

data/lib/terret/subagents.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Terret
+  # ctx[:subagents] — the delegation seam, sole-provider like
+  # ctx[:session_store] and ctx[:summarizer]. This is the fork provider; the
+  # seam, the other two providers plan §6.4 names, and the lifecycle below are
+  # docs/subagents.md §§1-3.
+  #
+  #   ctx[:subagents].run(prompt:, ctx:) # => Result(text:, session_id:, usage:, status:)
+  #
+  # `ctx:` is the CALLING AGENT's context and it is an explicit argument
+  # rather than a service ivar for one reason: it is what makes the
+  # no-escalation guarantee structural. No path through this provider can
+  # build a child from the root, so a child inherits the caller's roster and
+  # its install-time policy FLOOR — an agent whose FLOOR is Read and Grep
+  # cannot ask a child to run Bash. The qualifier matters (docs/subagents.md
+  # §3): a policy hot-*narrowed* mid-session does not carry to children spawned
+  # after it, because the child's session is fresh and holds no policy/updated,
+  # so it runs at the floor rather than at the parent's live, narrowed set. A
+  # narrowing that must reach children belongs in the floor (a config row).
+  class Subagents < Hames::Service
+    service_key :subagents
+    inject :loop, :sessions
+    config_schema({}) # spawns delegated agents; takes no config of its own
+
+    # `status` is the child's TURN status — :completed, :cancelled, :rejected
+    # or :empty (a failure raises instead). A caller rendering the child's text
+    # needs it to tell "had nothing to say" from "was stopped", and re-reading
+    # the child's log for a fact the turn already returned is a worse seam.
+    Result = Data.define(:text, :session_id, :usage, :status)
+
+    def start(ctx)
+      @ctx = ctx
+    end
+
+    # Nothing is captured from config, so a swapped row governs the very next
+    # delegation with nothing to re-derive.
+    def reconfigure(_config); end
+
+    # Spawn a child inside a fork of the caller's context, run one turn to
+    # completion on a fresh durable session, and hand back what it said, where
+    # it said it, and what it cost.
+    #
+    # The child's session is FRESH, not `Sessions#fork`ed: a subagent inherits
+    # its parent's capabilities, not its parent's transcript.
+    #
+    # AgentCapExceeded raises straight through rather than being wrapped: a
+    # refused spawn is the caller's answer, not something that happened inside
+    # a child.
+    def run(prompt:, ctx:)
+      sessions = @ctx[:sessions]
+      loop_service = @ctx[:loop]
+      session = sessions.create
+      agent = loop_service.spawn_agent(session_id: session.id,
+                                       id: "subagent-#{session.id}", parent: ctx)
+      # Marked before the turn can start: nothing routes an approval request
+      # for this session to a human, so the gate must deny rather than park on
+      # a verdict that can never arrive. A parked child would hold the parent's
+      # fiber forever and there is no one to unstick it.
+      agent.unattended = true
+      begin
+        # The ordinary Loop: same steps, same MAX_STEPS ceiling, same pipeline,
+        # same approvals gate, same allow list. run_turn's own input path is
+        # what appends the prompt as a durable user/message.
+        status = loop_service.run_turn(agent, prompt)
+        Result.new(text: final_text(sessions, session.id), session_id: session.id,
+                   usage: sessions.usage(session.id), status: status)
+      rescue StandardError => e
+        # A stack trace in a tool result is context the parent's model cannot
+        # act on and pays for on every subsequent request. The session id is
+        # the pointer to where the whole story actually is.
+        raise Tools::Failure,
+              "the subagent turn failed (#{e.class}); its session #{session.id} has the story"
+      ensure
+        dispose(loop_service, agent)
+      end
+    end
+
+    private
+
+    # The child's last word, projected from its log like every other
+    # model-visible fact. A turn that closed without one (rejected, empty, or
+    # cancelled before a first reply) answers nil, and the caller renders it.
+    def final_text(sessions, session_id)
+      sessions.derive_messages(session_id).reverse_each
+              .find { |m| m.role == :assistant }&.text
+    end
+
+    # Unconditional, including when the turn raised: the fork goes with the
+    # agent, so every tool, listener, and effect the child installed dies at
+    # the same moment. A disposal that itself fails must not replace the
+    # failure the caller is already being told about.
+    def dispose(loop_service, agent)
+      loop_service.dispose_agent(agent.id)
+    rescue StandardError => e
+      warn "terret: subagent #{agent.id} would not dispose: #{e.class}: #{e.message}"
+    end
+  end
+end

data/lib/terret/titler.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Terret
+  # ctx[:titler] — one durable title per session (plan §6.2's titler role,
+  # §12 M6). Rides the first turn/end: generates through the :titler model
+  # role when the roles map has one, else falls back to the first user line
+  # truncated to 40 chars. session/titled is metadata — projection-invisible,
+  # like the approval and policy events — so titling can never disturb
+  # derived context. The :role knob is read per call, so reconfigure is live
+  # by construction.
+  class Titler < Hames::Service
+    service_key :titler
+    inject :sessions, :llm
+    config_schema role: { type: [String, Symbol], default: :titler,
+                          doc: "llm role a title is generated under" }
+
+    PROMPT = "Title this conversation in at most six words. Reply with the title only."
+
+    def start(ctx)
+      @ctx = ctx
+      ctx.on("session/event") do |ev|
+        next unless ev.type == "turn/end"
+        next if @ctx[:sessions].title(ev.session_id)
+
+        title!(ev.session_id)
+      end
+    end
+
+    def reconfigure(_config); end
+
+    # Append a title now (re-titling is the caller's explicit choice; the
+    # listener above only ever titles once). Returns the event, or nil when
+    # there is nothing to title.
+    def title!(session_id)
+      sessions = @ctx[:sessions]
+      history = sessions.derive_messages(session_id)
+      return if history.empty?
+
+      title = (generate(history) || fallback(sessions.fetch(session_id).events)).to_s.strip
+      return if title.empty?
+
+      sessions.append(session_id, "session/titled", { title: title[0, 80] })
+    end
+
+    private
+
+    def generate(history)
+      request = LLM::Request.new(model: nil, system: PROMPT, messages: history, tools: [])
+      @ctx[:llm].stream(@ctx, role: config[:role] || :titler, request: request) { |_ev| }.text
+    rescue KeyError
+      nil # no :titler role configured — the fallback carries it
+    end
+
+    def fallback(events)
+      events.find { |e| e.type == "user/message" }&.payload&.[](:text)&.[](0, 40)
+    end
+  end
+end

data/lib/terret/tools.rb

@@ -3,7 +3,7 @@
 module Terret
   module Tools
     Definition = Data.define(:name, :description, :params, :handler,
-                             :mutating, :approval) do
+                             :mutating, :approval, :concurrency) do
       def schema = { name:, description:, parameters: params }
     end
 
@@ -17,42 +17,311 @@ module Terret
     # (truncate / redact).
     class Registry < Hames::Service
       service_key :tools
+      config_schema({}) # the tool registry takes no config
 
       def start(ctx)
         @ctx = ctx
         @defs = {}
+        @floor = nil
       end
 
+      # Returns the registration's disposer. The roster itself stays global
+      # (visibility is the AllowList's job, not this method's) — but the
+      # effect that puts a Definition in the roster is recorded on `ctx`,
+      # which defaults to the registry's own root and so preserves every
+      # existing call site. A caller that passes its forked agent ctx ties
+      # OWNERSHIP to that fork: disposing the agent reaps the registration,
+      # closing the M6-recorded bleed where an agent-registered tool (one
+      # that can carry filesystem authority) outlived the agent that made it.
       def register(name:, description:, params: {}, mutating: false,
-                   approval: :never, &handler)
+                   approval: :never, concurrency: :serial, ctx: @ctx, &handler)
         d = Definition.new(name: name.to_s, description:, params:, handler:,
-                           mutating:, approval:)
-        @ctx.effect do
+                           mutating:, approval:, concurrency:)
+        ctx.effect do
           @defs[d.name] = d
           -> { @defs.delete(d.name) }
         end
-        d
       end
 
       def schemas = @defs.values.map(&:schema)
       def fetch(name) = @defs.fetch(name.to_s)
 
-      def execute(call)
-        admitted = @ctx.waterfall("tools/pre_execute", call)
+      # Execution runs the three-waterfall pipeline: pre_execute (validate /
+      # veto / rewrite) -> execute (a provider may replace execution
+      # wholesale) -> post_execute (truncate / redact). Waterfalls dispatch
+      # on `ctx`, which callers set to the AGENT's forked context so
+      # per-agent policy listeners ride the fork (root listeners still run
+      # first — fork dispatch chains parent-first). ctx is required — a
+      # forgotten kwarg must fail loudly, not silently skip per-agent policy.
+      #
+      # One thing a handler is given beyond its arguments: a handler that
+      # declares a `session_id:` keyword receives the executing call's
+      # session. It is injected here and never model-supplied — it is not a
+      # property of any tool's params schema, and the merge in #handler_args
+      # puts the Call's own value LAST so an argument carrying that name
+      # cannot name somebody else's session.
+      def execute(call, ctx:)
+        admitted = ctx.waterfall("tools/pre_execute", call)
         return Result.new(id: call.id, content: nil, error: admitted.reason) if admitted.is_a?(Veto)
 
-        result = @ctx.waterfall("tools/execute", admitted) do |c|
-          d = fetch(c.name)
+        # The deny-by-default floor is AUTHORITATIVE. It runs here — on the
+        # exact call the pre_execute waterfall admitted, rewrites included —
+        # not as a waterfall listener a sibling could register ahead of and
+        # short-circuit past. A pre_execute listener can make policy stricter
+        # (a Veto above), never looser: it cannot admit a tool the floor
+        # denies, because that admission never reaches execution. This is the
+        # autonomous safety mechanism (docs/security.md); a listener from a
+        # third-party bundle must not be able to defeat it.
+        if @floor && (veto = @floor.call(admitted)).is_a?(Veto)
+          return Result.new(id: call.id, content: nil, error: veto.reason)
+        end
+
+        result = ctx.waterfall("tools/execute", admitted) do |c|
           begin
-            Result.new(id: c.id, content: d.handler.call(**c.args), error: nil)
+            d = fetch(c.name)
+            Result.new(id: c.id, content: d.handler.call(**handler_args(d, c)), error: nil)
+          rescue Failure => e
+            Result.new(id: c.id, content: nil, error: e.message)
           rescue => e
             Result.new(id: c.id, content: nil, error: "#{e.class}: #{e.message}")
           end
         end
-        @ctx.waterfall("tools/post_execute", result)
+        ctx.waterfall("tools/post_execute", result)
+      end
+
+      # Install the authoritative deny-by-default floor. The floor is a single
+      # predicate #execute consults on the admitted call, deliberately NOT a
+      # tools/pre_execute listener: a listener is a peer another row's listener
+      # can register ahead of and short-circuit past (the mount-pass bypass
+      # that defeated the floor), whereas this gate sees the call that will
+      # actually run and its Veto is final. The predicate answers a Veto to
+      # deny and anything else to admit. Recorded as an effect of the mounting
+      # row (ctx defaults to the Registry's own root), so unloading that row
+      # removes the floor; a second install replaces the first and disposal
+      # restores whatever it replaced. Only one floor is active — the
+      # deny-by-default policy is one floor, with per-session and per-agent
+      # variation layered above it (policy/updated and per-fork AllowLists).
+      def install_floor(ctx = @ctx, &predicate)
+        ctx.effect do
+          previous = @floor
+          # The floor is the autonomous safety mechanism, so a second install
+          # silently swapping it out is worth surfacing. Not refused — a
+          # legitimate re-mount or hot reconfigure disposes the old floor first
+          # (restoring @floor to nil) and then re-installs, so that path sees no
+          # previous floor and stays quiet; only a genuine replace-while-active
+          # warns.
+          if previous
+            warn "terret: install_floor replaced an active tool floor; the " \
+                 "deny-by-default safety floor is now the one just installed"
+          end
+          @floor = predicate
+          -> { @floor = previous }
+        end
+      end
+
+      private
+
+      # A handler that declares a `session_id:` keyword is asking which
+      # session it is running for. That is the one fact about a call that is
+      # not in its args and cannot be recovered from anywhere else: a forked
+      # agent scope is an anonymous Context, so a tool owning per-session
+      # state — a persistent shell, a named terminal — has no other way to
+      # keep one agent's state out of another's.
+      #
+      # Only handlers that declare it are handed it, so every registration
+      # that does not care keeps its exact signature (an unknown keyword
+      # would raise). And the call's own session is merged LAST: a model that
+      # writes `session_id` into its arguments is trying to name somebody
+      # else's shell, and here that argument simply loses.
+      #
+      # Both keyword shapes count. A handler written as a block reports an
+      # optional keyword as `:key` and a required one as `:keyreq`, and a
+      # lambda handler reports `:keyreq` too — the tool that needs its
+      # session must not depend on which of the three forms it was written
+      # in.
+      def handler_args(definition, call)
+        return call.args unless wants_session?(definition.handler)
+
+        call.args.merge(session_id: call.session_id)
+      end
+
+      def wants_session?(handler)
+        handler.parameters.any? { |kind, name| name == :session_id && %i[key keyreq].include?(kind) }
       end
     end
 
     Veto = Data.define(:reason)
+
+    # A domain failure whose message is the whole story: handlers raise it
+    # when the error is the tool's outcome, not a bug. Registry#execute logs
+    # it message-only; any other exception keeps its class name, because a
+    # crash's class is diagnostics, not noise.
+    Failure = Class.new(StandardError)
+
+    # Deny-by-default allow list (plan §6.3), hot-reloadable (§12 M6): the
+    # ACTIVE pattern set is the last durable policy/updated event in the
+    # call's session, falling back to the install-time patterns as the floor.
+    # update is an ordinary durable append — it takes effect on the very next
+    # call with no reinstall, and replay rebuilds it, so a hot-reloaded
+    # policy survives a restart while the floor only governs sessions that
+    # never updated. Patterns are File.fnmatch globs; matching is
+    # case-sensitive and "*" does not match dotfiles — both fail closed.
+    module AllowList
+      # A per-agent (or per-context) allow list as a tools/pre_execute listener.
+      # This is the right shape for an agent's OWN policy: it rides the agent's
+      # fork and can only make the effective policy STRICTER (a veto here stops
+      # the call). It is deliberately NOT the authoritative floor — a listener
+      # is a peer another listener can order itself ahead of. For the
+      # deny-by-default floor that no row's listener may bypass, see
+      # #install_floor.
+      def self.install(ctx, patterns)
+        floor = Array(patterns).map(&:to_s)
+        cache = new_cache
+        pre = ctx.on("tools/pre_execute") do |call, next_|
+          if admits?(ctx, call, floor, cache)
+            next_.(call)
+          else
+            Veto.new(reason: "#{call.name} is not on the allow list")
+          end
+        end
+        inval = install_invalidation(ctx, cache)
+
+        # Composite: tear the gate and its invalidation down together. Both are
+        # already recorded as effects of this context (so fork.dispose! reaps
+        # them); this is the handle a caller pulls to remove its list early.
+        lambda do
+          pre.call
+          inval.call
+        end
+      end
+
+      # The authoritative deny-by-default floor (docs/composition.md §6,
+      # docs/security.md). It runs the SAME per-session, hot-reloadable decision
+      # as #install, but wired into ctx[:tools] as the Registry's floor gate
+      # rather than as a tools/pre_execute listener. That placement is the whole
+      # point: the floor mounts in a later loader pass than a no-inject row, so
+      # as a listener it sat BEHIND that row's listener in the waterfall and a
+      # listener that admitted a call without delegating short-circuited past
+      # it. As the gate, it runs after the waterfall on the call that will
+      # actually execute, so no listener any row registers can bypass it.
+      def self.install_floor(ctx, patterns)
+        floor = Array(patterns).map(&:to_s)
+        cache = new_cache
+        gate = ctx[:tools].install_floor(ctx) do |call|
+          Veto.new(reason: "#{call.name} is not on the allow list") unless admits?(ctx, call, floor, cache)
+        end
+        inval = install_invalidation(ctx, cache)
+
+        lambda do
+          gate.call
+          inval.call
+        end
+      end
+
+      # The shared decision, used by both the per-agent listener and the floor
+      # gate: does the ACTIVE policy for this call's session admit its tool
+      # name? Patterns are File.fnmatch globs; matching is case-sensitive and
+      # "*" does not match dotfiles — both fail closed.
+      def self.admits?(ctx, call, floor, cache)
+        active = active_patterns(ctx, call.session_id, cache) || floor
+        active.any? { |p| File.fnmatch(p, call.name) }
+      end
+
+      # Per-install, never global: a fresh cache is a closure local of THIS
+      # install, so a forked agent scope, a hot policy swap, and the floor each
+      # get their own. Two installs sharing one would leak one agent's policy
+      # into another's — the cross-agent bleed this milestone closed. Keyed by
+      # session id; the value is the patterns from that session's last
+      # policy/updated, or nil for "no policy yet, fall to the floor" (nil is
+      # cached too, so a never-updated session also stops rescanning the log).
+      def self.new_cache = {}
+
+      # Log-first invalidation. The cache is a read-through of the durable log,
+      # never a second source of truth, so the ONLY write besides a miss is a
+      # policy/updated landing in the log. session/event is emitted on the
+      # context that mounts Sessions — the root of the fork chain, NOT a forked
+      # ctx — and a fork-registered listener would never see it, so we listen on
+      # root. Lifetime still follows the caller: wrapping root.on in ctx.effect
+      # records the teardown as an effect of THIS context, so disposing the
+      # agent (Loop#dispose_agent -> fork.dispose!) reaps the root listener too,
+      # and it also rides the composite disposer the callers return. Fan-out is
+      # synchronous and in seq order, so update's append has refreshed the entry
+      # before the next call reads it.
+      def self.install_invalidation(ctx, cache)
+        root = ctx
+        root = root.parent while root.parent
+        ctx.effect do
+          root.on("session/event") do |ev|
+            cache[ev.session_id] = ev.payload[:patterns] if ev.type == "policy/updated"
+          end
+        end
+      end
+
+      # Hot update: durable, per-session, last one wins.
+      def self.update(ctx, session_id, patterns)
+        ctx[:sessions].append(session_id, "policy/updated",
+                              { patterns: Array(patterns).map(&:to_s) })
+      end
+
+      # Read-through cache over the log projection. A hit returns the cached
+      # patterns-or-nil without touching the log; a miss derives once and
+      # stores the result. Concurrency: under the fiber scheduler a fiber
+      # yields only at an await, and neither this read/write nor the
+      # session/event writer awaits between touching the Hash — so same-sid
+      # operations cannot interleave and distinct sids are independent; a plain
+      # Hash needs no lock. An unknown session raises KeyError out of the
+      # derivation before any scan and before anything is stored, so it is NOT
+      # cached: the call re-derives (and re-warns) each time, and a deny-all
+      # never ossifies into an allow.
+      def self.active_patterns(ctx, session_id, cache)
+        cache.fetch(session_id) { cache[session_id] = current_patterns(ctx, session_id) }
+      rescue KeyError
+        warn "terret: no policy readable for session #{session_id.inspect}; denying every tool call"
+        []
+      end
+
+      # The pure log derivation the cache reads through: the patterns of the
+      # last durable policy/updated in the session, or nil if it never updated.
+      # Raises KeyError for a session this context cannot read (handled in
+      # active_patterns), which is why the rescue lives there and not here.
+      def self.current_patterns(ctx, session_id)
+        ctx[:sessions].fetch(session_id).events.reverse_each
+                      .find { |e| e.type == "policy/updated" }
+                      &.payload&.[](:patterns)
+      end
+    end
+
+    # AllowList as a config row, so a bundle can ship the deny-by-default
+    # floor the way it ships everything else (docs/composition.md §6). The
+    # module above is still the mechanism and still installable by hand; this
+    # is only the mounting. Its registrations are already effects of the
+    # mounting row, so unloading the row takes the gate with it.
+    #
+    # `patterns:` is the floor — the policy governing sessions that never
+    # issued a policy/updated of their own. Unconfigured means an empty floor,
+    # which denies every tool call.
+    class AllowListFloor < Hames::Service
+      service_key :allow_list
+      inject :tools, :sessions
+      config_schema patterns: { type: Array, default: [],
+                                doc: "tool-name globs the deny-by-default floor permits" }
+
+      def start(ctx)
+        @ctx = ctx
+        @disposer = AllowList.install_floor(ctx, config[:patterns] || [])
+      end
+
+      # Hot-reconfigure the floor. The base Service#reconfigure only warns, so a
+      # config/updated that TIGHTENS the floor (drops a pattern) would silently
+      # keep the looser patterns start captured — the deny-by-default policy
+      # left looser than the operator asked for. Tear the old gate and its
+      # invalidation down and re-install with the new patterns; this runs under
+      # with_owner(id), so the new registrations are owned by this row exactly
+      # as start's were, and take effect on the next call.
+      def reconfigure(config)
+        @disposer&.call
+        @disposer = AllowList.install_floor(@ctx, config[:patterns] || [])
+      end
+    end
   end
 end

data/lib/terret.rb

@@ -7,7 +7,7 @@ rescue LoadError
 end
 
 module Terret
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 
   # Event vocabulary. Durable events land in the session log; the rest are
   # live extension points. Modes are the public contract (see docs/events.md).
@@ -28,7 +28,16 @@ module Terret
     e.("tool/call",         :emit, durable: true, doc: "tool invocation requested by model")
     e.("tool/result",       :emit, durable: true, doc: "tool outcome")
     e.("context/injected",  :emit, durable: true, doc: "agent.inject landed in a request")
+    e.("session/compacted", :emit, durable: true,
+       doc: "history up to upto_seq replaced by summary (still model-visible)")
+    e.("approval/requested", :emit, durable: true, doc: "tool call parked awaiting a decision")
+    e.("approval/resolved",  :emit, durable: true, doc: "parked call decided (approve/deny)")
+    e.("policy/updated",   :emit, durable: true,
+       doc: "agent allow-list replaced (metadata; projection-invisible)")
+    e.("session/titled",   :emit, durable: true, doc: "session titled (metadata; projection-invisible)")
     # live extension points
+    e.("agent/disposed",    :emit,      doc: "an agent was disposed (session_id); reap its session-keyed runtime state")
+    e.("config/updated",    :emit,      doc: "a row's config was hot-swapped (id, config)")
     e.("session/event",     :emit,      doc: "fan-out of every durable append")
     e.("agent/pre_step",    :waterfall, doc: "rewrite or reject the claimed messages")
     e.("agent/request",     :waterfall, doc: "rewrite the outbound model request")
@@ -36,13 +45,21 @@ module Terret
     e.("tools/pre_execute",  :waterfall, doc: "validate, veto, or rewrite a call")
     e.("tools/execute",      :waterfall, doc: "a provider may replace execution")
     e.("tools/post_execute", :waterfall, doc: "truncate/redact the result")
+    e.("fs/authorize",       :waterfall, doc: "veto or admit an fs operation")
     e.("agent/turn_stopping", :serial,   doc: "ordered veto point before turn/end")
   end
 end
 
 require_relative "terret/llm"
+require_relative "terret/store"
 require_relative "terret/sessions"
 require_relative "terret/tools"
+require_relative "terret/redactor"
+require_relative "terret/credentials"
+require_relative "terret/approvals"
+require_relative "terret/compactor"
+require_relative "terret/titler"
 require_relative "terret/loop"
+require_relative "terret/subagents"
 
 Terret.declare_events!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terret-core
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Obie Fernandez
@@ -34,9 +34,16 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/terret.rb
+- lib/terret/approvals.rb
+- lib/terret/compactor.rb
+- lib/terret/credentials.rb
 - lib/terret/llm.rb
 - lib/terret/loop.rb
+- lib/terret/redactor.rb
 - lib/terret/sessions.rb
+- lib/terret/store.rb
+- lib/terret/subagents.rb
+- lib/terret/titler.rb
 - lib/terret/tools.rb
 homepage: https://terret.org
 licenses: