terret-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb6dbfe91797674f464068e08da10eb0d19289dc30d3a791c5c46d9450c9ff13
+  data.tar.gz: fa2cabe0f12d5fe1a94d9d14cb22686f9e6208dfd9b5a69316124ee1bf162ee5
+SHA512:
+  metadata.gz: c4cfee58e20514fdeb1e8f3d60e3336916c6c54e169377f1ff64ec1ba1d6373b6dc2a2a01c7f579ede66d0f49a92fc90151947910b9a4bfe5e895dca3ab4b426
+  data.tar.gz: c250f6994e87dc668bd6cc60d9e967ff8f1232b972cb0be4853c4c0ba9a257012450424701d93fc13b39106e2dbcb63d3cddf55abccfa5a4ec2ed9bd31a8a2ba

data/lib/terret/llm.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Terret
+  module LLM
+    # Provider-neutral vocabulary. Adapters translate these to wire formats.
+    Text       = Data.define(:text)
+    ToolCall   = Data.define(:id, :name, :args)
+    ToolResult = Data.define(:id, :content, :error)
+    Message    = Data.define(:role, :parts) do
+      def tool_calls = parts.grep(ToolCall)
+      def text = parts.grep(Text).map(&:text).join
+    end
+
+    Request = Data.define(:model, :system, :messages, :tools)
+
+    # Stream events yielded by adapters.
+    TextDelta   = Data.define(:text)
+    ToolCallEnd = Data.define(:tool_call)
+    MessageStop = Data.define(:stop_reason) # :end_turn | :tool_use
+
+    # ctx.llm — the adapter seam. `llm/stream` is a waterfall wrapping every
+    # request: middleware may rewrite the request or replace the stream.
+    class Service < Hames::Service
+      service_key :llm
+
+      def start(_ctx)
+        @adapters = {}
+        @roles    = config[:roles] || {} # :main => "fake/scripted"
+      end
+
+      def register_adapter(name, adapter)
+        @adapters[name.to_s] = adapter
+        -> { @adapters.delete(name.to_s) }
+      end
+
+      def resolve(role)
+        spec = @roles.fetch(role) { raise KeyError, "no model role #{role.inspect}" }
+        provider, model = spec.split("/", 2)
+        [@adapters.fetch(provider), model]
+      end
+
+      # Streams the request through the `llm/stream` waterfall; the base of
+      # the waterfall invokes the resolved adapter. Yields StreamEvents,
+      # returns the final assistant Message.
+      def stream(ctx, role:, request:, &on_event)
+        adapter, model = resolve(role)
+        req = request.with(model: model)
+        ctx.waterfall("llm/stream", req) do |final_req|
+          adapter.stream(final_req, &on_event)
+        end
+      end
+    end
+
+    # Deterministic scripted adapter for tests, demos, and record/replay.
+    # Script: array of hashes { text:, tool_calls: [ToolCall, ...] }.
+    class FakeAdapter
+      def initialize(script)
+        @script = script.dup
+      end
+
+      def stream(_request)
+        step = @script.shift or raise "FakeAdapter script exhausted"
+        parts = []
+        if (t = step[:text])
+          t.chars.each_slice(8) { |chunk| yield TextDelta.new(text: chunk.join) }
+          parts << Text.new(text: t)
+        end
+        calls = Array(step[:tool_calls])
+        calls.each do |tc|
+          yield ToolCallEnd.new(tool_call: tc)
+          parts << tc
+        end
+        yield MessageStop.new(stop_reason: calls.empty? ? :end_turn : :tool_use)
+        Message.new(role: :assistant, parts: parts)
+      end
+    end
+  end
+end

data/lib/terret/loop.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Terret
+  Claim = Data.define(:messages, :rejected, :reason) do
+    def self.of(messages) = new(messages:, rejected: false, reason: nil)
+    def self.reject(reason:) = new(messages: [], rejected: true, reason:)
+  end
+
+  class Agent
+    attr_reader :id, :session_id, :ctx
+    attr_accessor :status
+
+    def initialize(id:, session_id:, ctx:)
+      @id = id
+      @session_id = session_id
+      @ctx = ctx           # a forked, agent-scoped context
+      @inbox = []          # injected context waits here until a waking message
+      @status = :idle
+    end
+
+    def inject(text)
+      @inbox << text
+    end
+
+    def drain_inbox = @inbox.slice!(0..)
+  end
+
+  # ctx.loop — the default driver. A step is one model request plus the tool
+  # calls it makes; a turn is zero or more steps and closes once nothing is
+  # owed. The driver is itself a plugin: replace this row in config and every
+  # tool, adapter, and UI keeps working.
+  class Loop < Hames::Service
+    service_key :loop
+    inject :sessions, :tools, :llm, :prompt
+
+    MAX_STEPS = 25
+
+    def start(ctx)
+      @ctx = ctx
+    end
+
+    def spawn_agent(session_id:, id: "agent-#{session_id}")
+      Agent.new(id:, session_id:, ctx: @ctx.fork)
+    end
+
+    # Runs one turn for `input`. Returns the turn status symbol.
+    def run_turn(agent, input)
+      ctx      = agent.ctx
+      sessions = ctx[:sessions]
+      sid      = agent.session_id
+      agent.status = :running
+
+      sessions.append(sid, "turn/start", { agent: agent.id })
+      status = :completed
+      steps = 0
+
+      # claim next-step input plus anything waiting in the inbox
+      pending = [input, *agent.drain_inbox].compact
+
+      loop do
+        claim = ctx.waterfall("agent/pre_step", Claim.of(pending)) { |c| c }
+        if claim.rejected || (steps.zero? && claim.messages.empty? && pending.empty?)
+          # a rejected or empty first claim still closes a durable turn that
+          # spent no step, so the log records the attempt
+          status = claim.rejected ? :rejected : :empty
+          break
+        end
+
+        steps += 1
+        raise "runaway turn" if steps > MAX_STEPS
+
+        sessions.append(sid, "step/start", { n: steps })
+        claim.messages.each { |t| sessions.append(sid, "user/message", { text: t }) }
+        pending = []
+
+        history = sessions.derive_messages(sid)
+        request = LLM::Request.new(model: nil, system: ctx[:prompt].render(agent:),
+                                   messages: history, tools: ctx[:tools].schemas)
+        request = ctx.waterfall("agent/request", request)
+        sessions.assert_log_invariant!(sid, request.messages)
+
+        message = ctx[:llm].stream(ctx, role: :main, request: request) do |ev|
+          case ev
+          when LLM::TextDelta
+            sessions.append(sid, "assistant/chunk", { text: ev.text })
+          end
+        end
+        sessions.append(sid, "assistant/message", { parts: message.parts })
+
+        calls = message.tool_calls
+        if calls.empty?
+          sessions.append(sid, "step/end", { n: steps })
+          break # nothing owed
+        end
+
+        calls.each do |tc|
+          sessions.append(sid, "tool/call", { id: tc.id, name: tc.name, args: tc.args })
+          result = ctx[:tools].execute(
+            Tools::Call.new(id: tc.id, name: tc.name, args: tc.args, session_id: sid)
+          )
+          sessions.append(sid, "tool/result",
+                          { id: result.id, content: result.content, error: result.error })
+        end
+        sessions.append(sid, "step/end", { n: steps })
+        # tools owe another request -> next step
+      end
+
+      ctx.serial("agent/turn_stopping", agent)
+      sessions.append(sid, "turn/end", { status: status })
+      agent.status = :idle
+      status
+    end
+  end
+
+  # ctx.prompt — minimal prompt assembly: priority-ordered sections rendered
+  # per step; registration is an effect.
+  class Prompt < Hames::Service
+    service_key :prompt
+
+    def start(ctx)
+      @ctx = ctx
+      @sections = []
+    end
+
+    def register_section(name, priority: 100, &block)
+      entry = [priority, name.to_s, block]
+      @ctx.effect do
+        @sections << entry
+        -> { @sections.delete(entry) }
+      end
+    end
+
+    def render(env = {})
+      @sections.sort_by { |(p, n, _)| [p, n] }
+               .filter_map { |(_, _, b)| b.call(env) }
+               .join("\n\n")
+    end
+  end
+end

data/lib/terret/sessions.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+require "json"
+
+module Terret
+  SessionEvent = Data.define(:id, :session_id, :seq, :at, :type, :payload)
+
+  class LogInvariantViolation < StandardError; end
+
+  # ctx.sessions — the append-only session log. The single source of the
+  # context the model sees: derive_messages projects model history from it,
+  # and a digest invariant asserts that what goes out to an adapter is
+  # exactly what replaying the log yields ("model-visible means logged").
+  class Sessions < Hames::Service
+    service_key :sessions
+
+    Session = Struct.new(:id, :events, :parent_id, keyword_init: true)
+
+    def start(ctx)
+      @ctx = ctx
+      @store = {}
+      @dir = config[:jsonl_dir] # optional persistence
+    end
+
+    def create(id: SecureRandom.hex(6), parent_id: nil)
+      s = Session.new(id:, events: [], parent_id:)
+      @store[id] = s
+      append(id, "session/created", { parent_id: })
+      s
+    end
+
+    def fetch(id) = @store.fetch(id)
+
+    def append(session_id, type, payload = {})
+      decl = Hames.event(type)
+      raise Hames::ContractError, "#{type} is not a durable event" unless decl.durable
+
+      s = fetch(session_id)
+      ev = SessionEvent.new(
+        id: SecureRandom.hex(8), session_id:, seq: s.events.length,
+        at: Time.now.utc, type: type.to_s, payload: payload
+      )
+      s.events << ev
+      persist(ev)
+      @ctx.emit("session/event", ev)
+      ev
+    end
+
+    # Project provider-neutral model history from the durable log.
+    def derive_messages(session_id, upto: nil)
+      events = fetch(session_id).events
+      events = events.take(upto) if upto
+      events.filter_map do |ev|
+        case ev.type
+        when "user/message", "context/injected"
+          LLM::Message.new(role: :user, parts: [LLM::Text.new(text: ev.payload[:text])])
+        when "assistant/message"
+          LLM::Message.new(role: :assistant, parts: ev.payload[:parts])
+        when "tool/result"
+          LLM::Message.new(role: :tool, parts: [
+            LLM::ToolResult.new(id: ev.payload[:id], content: ev.payload[:content],
+                                error: ev.payload[:error])
+          ])
+        end
+      end
+    end
+
+    # The enforcement point for "model-visible means logged": the loop calls
+    # this with the message list it is about to send; a mismatch against the
+    # log projection raises in dev/test.
+    def assert_log_invariant!(session_id, outbound_messages)
+      derived = derive_messages(session_id)
+      return if digest(derived) == digest(outbound_messages)
+
+      raise LogInvariantViolation,
+            "outbound request diverges from session log projection for #{session_id}"
+    end
+
+    def fork(source_id, boundary: nil, child_id: SecureRandom.hex(6))
+      src = fetch(source_id)
+      child = Session.new(id: child_id, events: [], parent_id: source_id)
+      @store[child_id] = child
+      events = boundary ? src.events.take(boundary) : src.events.dup
+      events.each { |ev| child.events << ev.with(session_id: child_id) }
+      append(child_id, "session/forked", { from: source_id, boundary: boundary })
+      child
+    end
+
+    private
+
+    def digest(messages)
+      Digest::SHA256.hexdigest(messages.map(&:inspect).join("\x1e"))
+    end
+
+    def persist(ev)
+      return unless @dir
+
+      File.open(File.join(@dir, "#{ev.session_id}.jsonl"), "a") do |f|
+        f.puts JSON.generate(type: ev.type, seq: ev.seq, at: ev.at.iso8601,
+                             payload: ev.payload.inspect)
+      end
+    end
+  end
+end

data/lib/terret/tools.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Terret
+  module Tools
+    Definition = Data.define(:name, :description, :params, :handler,
+                             :mutating, :approval) do
+      def schema = { name:, description:, parameters: params }
+    end
+
+    Call   = Data.define(:id, :name, :args, :session_id)
+    Result = Data.define(:id, :content, :error)
+
+    # ctx.tools — scoped registry + guarded execution pipeline. Registration
+    # is an effect (unloading a plugin removes its tools). Execution runs the
+    # three-waterfall pipeline: pre_execute (validate / veto / rewrite) ->
+    # execute (a provider may replace execution wholesale) -> post_execute
+    # (truncate / redact).
+    class Registry < Hames::Service
+      service_key :tools
+
+      def start(ctx)
+        @ctx = ctx
+        @defs = {}
+      end
+
+      def register(name:, description:, params: {}, mutating: false,
+                   approval: :never, &handler)
+        d = Definition.new(name: name.to_s, description:, params:, handler:,
+                           mutating:, approval:)
+        @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)
+        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)
+          begin
+            Result.new(id: c.id, content: d.handler.call(**c.args), error: nil)
+          rescue => e
+            Result.new(id: c.id, content: nil, error: "#{e.class}: #{e.message}")
+          end
+        end
+        @ctx.waterfall("tools/post_execute", result)
+      end
+    end
+
+    Veto = Data.define(:reason)
+  end
+end

data/lib/terret.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+begin
+  require "hames"
+rescue LoadError
+  require_relative "../../hames/lib/hames" # monorepo path source
+end
+
+module Terret
+  VERSION = "0.1.0"
+
+  # Event vocabulary. Durable events land in the session log; the rest are
+  # live extension points. Modes are the public contract (see docs/events.md).
+  def self.declare_events!
+    e = ->(name, mode, durable: false, doc: nil) {
+      Hames.event(name, mode:, durable:, doc:)
+    }
+    # durable session events
+    e.("session/created",   :emit, durable: true, doc: "session opened")
+    e.("session/forked",    :emit, durable: true, doc: "lineage record")
+    e.("turn/start",        :emit, durable: true, doc: "turn opened")
+    e.("turn/end",          :emit, durable: true, doc: "turn closed with status")
+    e.("step/start",        :emit, durable: true, doc: "model step opened")
+    e.("step/end",          :emit, durable: true, doc: "model step closed")
+    e.("user/message",      :emit, durable: true, doc: "entered user input")
+    e.("assistant/chunk",   :emit, durable: true, doc: "raw stream delta (replay/UI fidelity)")
+    e.("assistant/message", :emit, durable: true, doc: "completed assistant message")
+    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")
+    # live extension points
+    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")
+    e.("llm/stream",        :waterfall, doc: "wrap/replace the adapter stream")
+    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.("agent/turn_stopping", :serial,   doc: "ordered veto point before turn/end")
+  end
+end
+
+require_relative "terret/llm"
+require_relative "terret/sessions"
+require_relative "terret/tools"
+require_relative "terret/loop"
+
+Terret.declare_events!

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: terret-core
+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: hames
+  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 core of the Terret agent harness: an append-only session log that
+  is the single source of model-visible truth, a scoped tool registry with a vetoable
+  execution pipeline, the agent turn/step loop as a replaceable plugin, and a provider-neutral
+  LLM seam.'
+email:
+- obiefernandez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/terret.rb
+- lib/terret/llm.rb
+- lib/terret/loop.rb
+- lib/terret/sessions.rb
+- lib/terret/tools.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: 'Terret agent harness core: session log, tools pipeline, agent loop'
+test_files: []