little_ghost 0.1.0

data/lib/little_ghost/run_context.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # RunContext gives tools and workflows one place for shared state, cancellation,
+  # deadlines, checkpoints, and accumulated usage. It travels with work inside a
+  # run without becoming global process state.
+  #
+  # Tools and workflows use it to share JSON-like state, check
+  # cancellation and deadlines, checkpoint messages, and accumulate usage.
+  # Access to framework-managed fields is thread-safe.
+  class RunContext
+    # Shared state, cancellation, deadline, metadata, operation identity, and
+    # durable conversation identity for the current work.
+    attr_reader :state, :cancellation_token, :deadline, :metadata,
+      :agent_operation_id, :conversation_id
+
+    # Creates a context with optional checkpoint and interruption state.
+    def initialize(
+      state: {},
+      cancellation_token: Support::CancellationToken.new,
+      deadline: nil,
+      metadata: {},
+      checkpoint: nil,
+      conversation_id: nil,
+      interruption_metadata: nil,
+      interruption_ids: []
+    )
+      if conversation_id
+        conversation_id = String(conversation_id)
+        raise ArgumentError, "conversation_id cannot be empty" if conversation_id.empty?
+        conversation_id = conversation_id.dup.freeze
+      end
+      @state = state
+      @cancellation_token = cancellation_token
+      @deadline = deadline
+      @metadata = metadata.freeze
+      @checkpoint = checkpoint
+      @conversation_id = conversation_id
+      @usage = Usage.new
+      @usage_mutex = Mutex.new
+      @structured_result = nil
+      @structured_result_mutex = Mutex.new
+      @agent_operation_id = nil
+      @agent_operation_id_mutex = Mutex.new
+      @interruption_mutex = Mutex.new
+      @interruption_metadata = interruption_metadata&.to_h
+      @interruption_ids = Array(interruption_ids).map { |id| String(id).dup.freeze }.freeze
+    end
+
+    # Raises LittleGhost::CancelledError or LittleGhost::DeadlineExceededError
+    # when execution should stop.
+    def check!
+      cancellation_token.raise_if_cancelled!
+      raise DeadlineExceededError, "The run deadline was reached" if deadline && Time.now >= deadline
+    end
+
+    # Sends +messages+ and current state to the configured checkpoint callback.
+    # With no checkpoint callback, this method does nothing and returns +nil+.
+    def checkpoint(messages)
+      return unless @checkpoint
+
+      if agent_operation_id
+        @checkpoint.call(messages:, state:, parent_operation_id: agent_operation_id)
+      else
+        @checkpoint.call(messages:, state:)
+      end
+    end
+
+    # Adds +value+ to accumulated model usage.
+    def record_usage(value)
+      @usage_mutex.synchronize { @usage += value }
+    end
+
+    # Takes a snapshot of accumulated usage.
+    def usage
+      @usage_mutex.synchronize { @usage }
+    end
+
+    # Calculates seconds remaining before the deadline.
+    #
+    # When +maximum+ is provided, the result is capped at that value. With no
+    # deadline, returns +maximum+.
+    def remaining_time(maximum = nil)
+      check!
+      return maximum unless deadline
+
+      remaining = deadline - Time.now
+      maximum ? [remaining, maximum].min : remaining
+    end
+
+    # Stores a validated LittleGhost::StructuredResult and returns it.
+    def submit_structured_result(result)
+      @structured_result_mutex.synchronize { @structured_result = result }
+      result
+    end
+
+    # Finds the latest validated structured result, if any.
+    def structured_result
+      @structured_result_mutex.synchronize { @structured_result }
+    end
+
+    def interruption_metadata # :nodoc:
+      @interruption_mutex.synchronize { @interruption_metadata }
+    end
+
+    def interruption_ids # :nodoc:
+      @interruption_mutex.synchronize { @interruption_ids }
+    end
+
+    def activate_interruption(metadata:, ids:) # :nodoc:
+      value = metadata&.to_h
+      values = Array(ids).map { |id| String(id).dup.freeze }.freeze
+      @interruption_mutex.synchronize do
+        @interruption_metadata = value
+        @interruption_ids = values
+      end
+    end
+
+    def bind_agent_operation_id(operation_id) # :nodoc:
+      @agent_operation_id_mutex.synchronize do
+        if @agent_operation_id && @agent_operation_id != operation_id
+          raise Error, "run context is already bound to an agent operation"
+        end
+
+        @agent_operation_id ||= operation_id
+      end
+    end
+  end
+end

data/lib/little_ghost/run_result.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Associates a validated structured value with its declared schema name.
+  StructuredResult = Data.define(:schema_name, :value) # :nodoc:
+
+  # RunResult gives callers one final view of an agent or workflow invocation.
+  # It includes the response, usage, updated conversation, state, and any
+  # validated structured value.
+  #
+  # Use #output when the caller should accept either structured or textual
+  # agents. It returns the validated structured value when present and #text
+  # otherwise.
+  RunResult = Data.define(:message, :stop_reason, :usage, :messages, :state, :structured_result) do # :nodoc:
+    def initialize(message:, stop_reason:, usage:, messages:, state:, structured_result: nil)
+      super
+    end
+
+    # Reads the final message text, or an empty string when no message exists.
+    def text
+      message&.text.to_s
+    end
+
+    # Indicates whether the run produced a validated structured result.
+    def structured?
+      !structured_result.nil?
+    end
+
+    # Uses the structured value when present and otherwise #text.
+    def output
+      structured? ? structured_result.value : text
+    end
+  end
+
+  # Associates a validated structured value with its declared schema name.
+  #
+  #   result = LittleGhost::StructuredResult.new(
+  #     schema_name: "support_research",
+  #     value: {"summary" => "The transfer is still settling."}
+  #   )
+  #   result.value.fetch("summary") # => "The transfer is still settling."
+  class StructuredResult < Data # :doc:
+    ##
+    # :singleton-method: new
+    # :call-seq:
+    #   new(schema_name:, value:) -> StructuredResult
+    #
+    # Associates +value+ with the schema that validated it.
+
+    ##
+    # :attr_reader: schema_name
+    # The name declared with <tt>Agent.result_schema</tt>.
+
+    ##
+    # :attr_reader: value
+    # The locally validated application value.
+  end
+
+  # RunResult gives callers one final view of an agent or workflow invocation.
+  # It includes the response, usage, updated conversation, state, and any
+  # validated structured value.
+  #
+  # Use #output when the caller should accept either structured or textual
+  # agents. It returns the validated structured value when present and #text
+  # otherwise.
+  class RunResult < Data # :doc:
+    ##
+    # :singleton-method: new
+    # :call-seq:
+    #   new(message:, stop_reason:, usage:, messages:, state:,
+    #       structured_result: nil) -> RunResult
+    #
+    # Creates the terminal value for one agent or workflow invocation.
+
+    ##
+    # :attr_reader: message
+    # The final assistant Message, or +nil+ when no message was produced.
+
+    ##
+    # :attr_reader: stop_reason
+    # The normalized reason the terminal model stream stopped.
+
+    ##
+    # :attr_reader: usage
+    # The Usage accumulated across this invocation.
+
+    ##
+    # :attr_reader: messages
+    # The complete, updated conversation.
+
+    ##
+    # :attr_reader: state
+    # The application state at the end of the invocation.
+
+    ##
+    # :attr_reader: structured_result
+    # The validated StructuredResult, or +nil+ for a textual result.
+
+    ##
+    # :method: text
+    # Reads the final message text, or an empty string when no message exists.
+
+    ##
+    # :method: structured?
+    # Indicates whether the invocation produced a validated structured result.
+
+    ##
+    # :method: output
+    # Uses the structured value when present and otherwise #text.
+  end
+end

data/lib/little_ghost/runtime/hook.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  class Runtime
+    # Hooks let applications prepare runs, transform interruptions, and map
+    # errors to caller-safe messages.
+    #
+    # Hooks are instantiated once per Runtime in configuration order. Override
+    # only the methods needed and return the supplied value when leaving it
+    # unchanged.
+    #
+    #   class TenantHook < LittleGhost::Runtime::Hook
+    #     def prepare_run(run)
+    #       run.register(TenantConnection.new(run.invocation.actor_id))
+    #       run
+    #     end
+    #   end
+    class Hook
+      # Prepares a newly built Run. Resources registered on the run share its
+      # lifecycle and close in reverse order.
+      def prepare_run(run) = run
+
+      # Transforms an interruption payload before it reaches the agent.
+      def prepare_interruption(_run, payload) = payload
+
+      # Returns a caller-safe error message, or nil to defer to later hooks and
+      # the runtime default. Avoid exposing secrets or internal exception text.
+      def error_message(_error, _run) = nil
+    end
+  end
+end

data/lib/little_ghost/runtime.rb

@@ -0,0 +1,392 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "configuration"
+
+module LittleGhost
+  # Prepare the shared services that agents and workflows use across many runs.
+  # A runtime owns model resolution, loading, persistence, lookup paths, hooks,
+  # and resource factories for one Ruby setup.
+  #
+  #   configuration = LittleGhost::Configuration.new(
+  #     root: Dir.pwd,
+  #     models: CustomerSupportModels,
+  #     default_model: "customer_support",
+  #     service_name: "support-api"
+  #   )
+  #   runtime = LittleGhost::Runtime.new(configuration: configuration)
+  #
+  #   runtime.service_name # => "support-api"
+  #   runtime.root == Pathname.new(File.realpath(Dir.pwd)) # => true
+  #
+  # Without explicit +settings+, construction canonicalizes the root, loads
+  # +config/little_ghost.rb+ once through the Configuration, snapshots settings,
+  # configures instrumentation, eager-loads application constants, and builds the
+  # selected model registry and session store. Supplying +settings+ is the
+  # lower-level path used to create a sibling runtime from an existing snapshot.
+  #
+  # Reuse a runtime across runs. +build_run+ creates any missing workspace and
+  # sandbox, transfers ownership only after both are built, and closes partial
+  # resources if construction fails. +build+ creates a sibling with explicit
+  # overrides and reuses the loader only when the application root is unchanged.
+  #
+  # Startup emits structured lifecycle instrumentation; a failed phase emits a
+  # failure event, flushes instrumentation, and re-raises the original exception.
+  # Session actor resolution must use trusted authenticated identity for tenant
+  # isolation. The default UnrestrictedSandbox is convenient application plumbing,
+  # not a security boundary for untrusted work.
+  class Runtime
+    # The snapshotted setup and materialized services used by new runs.
+    attr_reader :configuration, :settings, :root, :loader, :prompt_paths, :skill_paths,
+      :skill_resource_root, :models, :session_store, :workspace_class, :sandbox_class,
+      :runtime_hooks
+
+    # Starts a runtime from +configuration+ or an existing settings snapshot.
+    def initialize(configuration:, settings: nil)
+      @startup_started_at = monotonic_time
+      @startup_phase = "configuration"
+      @startup_reported = false
+
+      begin
+        raise ArgumentError, "configuration must be a LittleGhost::Configuration" unless configuration.is_a?(Configuration)
+
+        @configuration = configuration
+        if settings
+          @settings = settings
+        else
+          bootstrap_root = canonical_application_root(configuration.root)
+          configuration.load_file!(root: bootstrap_root)
+          @settings = configuration.settings(root: bootstrap_root)
+        end
+        report_startup(status: "starting")
+        @startup_reported = true
+        @root = canonical_application_root(@settings.fetch(:root))
+        @skill_resource_root = @settings[:skill_resource_root]
+        @workspace_class = @settings.fetch(:workspace)
+        @sandbox_class = @settings.fetch(:sandbox)
+        @runtime_hooks = build_runtime_hooks(@settings[:runtime_hooks])
+
+        @startup_phase = "instrumentation"
+        subscribe_instrumentation(@settings[:instrumentation_subscribers])
+        emit_startup(:runtime_start)
+
+        @startup_phase = "loader"
+        @loader = @settings[:loader] || Support::Loader.new(root: @root)
+        loader.setup
+        loader.eager_load
+
+        @startup_phase = "models"
+        @invocation_class = @settings[:invocation] || Invocation
+        @models = build_service(@settings[:models], default: -> { DefaultModelRegistry.new })
+        @default_model = @settings.fetch(:default_model, "default").to_s
+
+        @startup_phase = "session_store"
+        @session_store = build_session_store(@settings[:session_store])
+        @session_actor = @settings[:session_actor]
+
+        @startup_phase = "prompts"
+        @prompt_paths = build_lookup_paths(:prompt_paths)
+        @skill_paths = build_lookup_paths(:skill_paths)
+
+        @startup_phase = "agent_builder"
+        @agent_builder = AgentBuilder.new(
+          runtime: self,
+          prompt_paths: @prompt_paths,
+          resolve_agent: method(:resolve_agent_class)
+        )
+
+        @startup_phase = "complete"
+        emit_startup(:runtime_stop, outcome: "ready")
+        report_startup(status: "ready")
+      rescue => error
+        unless @startup_reported
+          report_startup(status: "starting")
+          @startup_reported = true
+        end
+        emit_startup(:runtime_stop, outcome: "failed", error:)
+        Instrumentation.flush
+        report_startup(status: "failed", error:)
+        raise
+      end
+    end
+
+    # Creates a sibling runtime with explicit setting overrides.
+    def build(**overrides)
+      values = @settings.merge(overrides)
+      values[:root] = canonical_application_root(values.fetch(:root))
+      values[:loader] = loader unless overrides.key?(:loader) || overrides.key?(:root)
+      self.class.new(
+        configuration:,
+        settings: values
+      )
+    end
+
+    # Coerces an application payload into the configured Invocation class.
+    def parse(payload)
+      payload.is_a?(@invocation_class) ? payload : @invocation_class.new(payload)
+    end
+
+    # Creates a Run and transfers ownership of newly created workspace and
+    # sandbox resources to it.
+    def build_run(
+      payload,
+      agent_class:,
+      entrypoint_class: agent_class,
+      workspace: nil,
+      sandbox: nil
+    )
+      owned_resources = []
+      workspace ||= build_workspace.tap { |resource| owned_resources << resource }
+      sandbox ||= build_sandbox(workspace:).tap { |resource| owned_resources << resource }
+      run = Run.new(
+        invocation: parse(payload),
+        runtime: self,
+        agent_class:,
+        entrypoint_class:,
+        workspace:,
+        sandbox:
+      )
+      owned_resources.each { |resource| run.register(resource) }
+      prepare_run(run)
+    rescue
+      if run
+        run.close
+      else
+        close_resources(owned_resources)
+      end
+      raise
+    end
+
+    # Instantiates the configured workspace, or a root-scoped Workspace by default.
+    def build_workspace
+      return workspace_class.new if workspace_class
+
+      Workspace.new(root: root)
+    end
+
+    # Instantiates the configured sandbox around +workspace+, or an unrestricted
+    # sandbox by default.
+    def build_sandbox(workspace:)
+      return sandbox_class.new(workspace:) if sandbox_class
+
+      UnrestrictedSandbox.new(workspace:)
+    end
+
+    # :nodoc:
+    def build_agent(
+      agent_class_or_name,
+      run:,
+      model: nil,
+      tools: [],
+      agent_path: Subagents::AgentPath::ROOT
+    )
+      @agent_builder.build(agent_class_or_name, run:, model:, tools:, agent_path:)
+    end
+
+    # The low-cardinality service name attached to runtime telemetry.
+    def service_name
+      @settings&.[](:service_name) || default_service_name
+    end
+
+    def model_for(agent_class, run) # :nodoc:
+      role = agent_class.model_role(run.invocation) || @default_model
+      models.resolve(role, invocation: run.invocation, run:)
+    end
+
+    def open_session(run) # :nodoc:
+      Session.new(
+        id: run.invocation.session_id,
+        actor_id: session_actor_for(run.invocation),
+        store: session_store,
+        operation_id: run.operation_id
+      )
+    end
+
+    def prepare_run(run) # :nodoc:
+      runtime_hooks.each { |hook| hook.prepare_run(run) }
+      run
+    end
+
+    def prepare_interruption(run, payload) # :nodoc:
+      runtime_hooks.reduce(payload) do |prepared, hook|
+        hook.prepare_interruption(run, prepared)
+      end
+    end
+
+    def open_subagent_session(run, conversation_id) # :nodoc:
+      parent_link = Subagents::Manager.parent_link(run.session)
+      Session.new(
+        id: Subagents::Manager.conversation_session_id(conversation_id),
+        actor_id: session_actor_for(run.invocation),
+        store: session_store,
+        operation_id: run.operation_id,
+        metadata: {
+          "little_ghost_kind" => "subagent_conversation",
+          "little_ghost_parent_link" => parent_link,
+          "little_ghost_conversation_id" => conversation_id
+        }
+      )
+    end
+
+    def session_actor_for(invocation) # :nodoc:
+      @session_actor ? @session_actor.call(invocation) : invocation.actor_id
+    end
+
+    def template_locals(run:, agent:) # :nodoc:
+      {invocation: run.invocation, run:, agent:}.merge(agent.prompt_locals)
+    end
+
+    def error_message(error, run) # :nodoc:
+      runtime_hooks.each do |hook|
+        message = hook.error_message(error, run)
+        return message if message
+      end
+
+      default_error_message(error, run)
+    end
+
+    def default_error_message(error, _run) # :nodoc:
+      return error.message if error.is_a?(UnsupportedInputError)
+      return error.message if error.is_a?(ToolLoopError)
+      return "The model reached its output limit before completing a response. Please retry with a narrower request." if error.is_a?(OutputLimitError)
+      if error.is_a?(MalformedToolCallError)
+        return "The model returned an invalid tool call before completing the response. Please retry with a narrower request."
+      end
+
+      "Agent failed: #{error.class}"
+    end
+
+    def resolve_agent(value) # :nodoc:
+      resolve_agent_class(value)
+    end
+
+    private
+
+    def close_resources(resources)
+      resources.reverse_each do |resource|
+        resource.close if resource.respond_to?(:close)
+      rescue
+        nil
+      end
+    end
+
+    def build_service(value, default:)
+      value ||= default.call
+      value.is_a?(Class) ? value.new : value
+    end
+
+    def build_runtime_hooks(hook_classes)
+      Array(hook_classes).map(&:new)
+    end
+
+    def build_session_store(definition)
+      return SessionStores::Memory.new unless definition
+
+      provider = definition.fetch(:provider)
+      options = definition.except(:provider)
+      store = provider.new(**options)
+      unless store.is_a?(SessionStore)
+        raise ConfigurationError, "session_store must be a LittleGhost::SessionStore"
+      end
+
+      store
+    end
+
+    def subscribe_instrumentation(subscribers)
+      Array(subscribers).each { |subscriber| Instrumentation.subscribe(subscriber) }
+    end
+
+    def default_service_name
+      return @settings[:service_name].to_s if @settings&.[](:service_name)
+
+      "little-ghost"
+    end
+
+    def emit_startup(name, outcome: nil, error: nil)
+      attributes = {
+        service_name: service_name,
+        startup_phase: @startup_phase,
+        duration_ms: startup_duration_ms,
+        outcome:
+      }.compact
+      if error
+        attributes[:error_type] = error.class.name
+        attributes[:diagnostic_exception] = JSON.generate(diagnostic_exception(error))
+      end
+      if name == :runtime_start
+        @startup_handle = Instrumentation.start(:runtime, parent: nil, **attributes)
+      else
+        @startup_handle&.finish(**attributes)
+      end
+    end
+
+    def report_startup(status:, error: nil)
+      payload = {
+        status:,
+        phase: @startup_phase,
+        service_name:
+      }
+      payload[:duration_ms] = startup_duration_ms unless status == "starting"
+      payload[:error_type] = error.class.name if error
+      return Events.error("little_ghost.runtime.startup", payload) if error
+
+      Events.info("little_ghost.runtime.startup", payload)
+    end
+
+    def diagnostic_exception(error)
+      {
+        type: error.class.name,
+        message: error.message,
+        stacktrace: Array(error.backtrace).join("\n")
+      }
+    end
+
+    def startup_duration_ms
+      ((monotonic_time - @startup_started_at) * 1_000).round(3)
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def canonical_application_root(value)
+      path = Pathname.new(File.realpath(File.expand_path(value)))
+      raise ConfigurationError, "application root must be a directory" unless path.directory?
+
+      path.freeze
+    rescue Errno::ENOENT
+      raise ConfigurationError, "application root must exist"
+    end
+
+    def resolve_agent_class(value)
+      klass = if value.is_a?(String) || value.is_a?(Symbol)
+        Object.const_get(value.to_s)
+      else
+        value
+      end
+      raise ConfigurationError, "agent must inherit from LittleGhost::Agent" unless klass.is_a?(Class) && klass <= Agent
+
+      klass
+    rescue NameError
+      klass = loader.constant(value)
+      raise ConfigurationError, "agent must inherit from LittleGhost::Agent" unless klass.is_a?(Class) && klass <= Agent
+
+      klass
+    end
+
+    def build_lookup_paths(name)
+      configured = Array(@settings.fetch(name))
+      default = if name == :prompt_paths
+        Configuration::DEFAULT_PROMPT_PATHS
+      else
+        Configuration::DEFAULT_SKILL_PATHS
+      end
+      roots = configured.map do |path|
+        expanded = File.expand_path(path, root)
+        boundary = default.include?(path.to_s) ? root : nil
+        Lookup::Root.new(path: expanded, boundary:)
+      end
+      PathSet.new(roots)
+    end
+  end
+end