little_ghost 0.4.0 → 0.5.0

data/lib/little_ghost/assembly_builder.rb

@@ -12,11 +12,11 @@ module LittleGhost
     end
   end
 
-  # The immutable, executable snapshot produced by an AssemblyBuilder.
+  # A complete Assembly configuration produced by an AssemblyBuilder.
   #
   # Runtime and other builders accept a definition anywhere they accept an
-  # Assembly reference. +implementation+ is the sealed class instantiated for
-  # this snapshot.
+  # Assembly reference. +implementation+ is the Assembly subclass used for
+  # executions built from this definition.
   class AssemblyDefinition < Data # :doc:
     ##
     # :attr_reader: kind
@@ -24,15 +24,15 @@ module LittleGhost
 
     ##
     # :attr_reader: assembly_id
-    # The stable identifier captured by the snapshot.
+    # The Assembly identifier at the time the definition was built.
 
     ##
     # :attr_reader: description
-    # The human-readable description captured by the snapshot.
+    # The human-readable description at the time the definition was built.
 
     ##
     # :attr_reader: implementation
-    # The sealed Assembly subclass used to build executions.
+    # The Assembly subclass used to build executions.
   end
 
   # Builds an Assembly when its participants or routes are discovered at runtime.
@@ -51,10 +51,10 @@ module LittleGhost
   #
   #   run = graph.ask("Can I get a refund?")
   #
-  # A builder remains mutable. Each build or invocation snapshots declaration
-  # containers and referenced Assembly definitions, so later builder changes
-  # affect only future executions. Executable Ruby closures and the external
-  # objects they reference remain live trusted application code.
+  # A builder remains mutable. Each build or invocation copies its declarations
+  # and referenced Assembly definitions. Later builder changes affect future
+  # executions without changing an Assembly already built. Ruby closures and
+  # the objects they reference remain live application code.
   class AssemblyBuilder
     # Optional Runtime reused by standalone executions from this builder.
     attr_reader :runtime
@@ -87,13 +87,13 @@ module LittleGhost
     # Returns +:agent+, +:workflow+, +:swarm+, or +:graph+.
     def assembly_kind = self.class.assembly_kind
 
-    # Validates the current snapshot and returns this mutable builder.
+    # Validates the builder's current declarations and returns this builder.
     def validate!
       definition
       self
     end
 
-    # Returns an immutable, recursively snapshotted definition.
+    # Returns a complete definition for the builder's current declarations.
     def definition
       stack = Thread.current[:little_ghost_assembly_definition_stack] ||= []
       identity = base || self
@@ -118,7 +118,7 @@ module LittleGhost
       Thread.current[:little_ghost_assembly_definition_stack] = nil if stack && stack.empty?
     end
 
-    # Builds one execution instance from the current definition snapshot.
+    # Builds one execution instance from the current declarations.
     def build(runtime: self.runtime, run: nil)
       snapshot = definition
       return (runtime || run.runtime).build_assembly(snapshot, run:) if run
@@ -126,10 +126,10 @@ module LittleGhost
       snapshot.implementation.new(runtime:)
     end
 
-    # Executes a standalone snapshot and returns its Run.
+    # Executes the current declarations and returns their Run.
     def ask(message, **options) = build.ask(message, **options)
 
-    # Lazily streams a standalone snapshot.
+    # Lazily streams an execution built from the current declarations.
     def stream_ask(message, **options)
       snapshot = definition
       Enumerator.new do |events|
@@ -137,13 +137,13 @@ module LittleGhost
       end
     end
 
-    # Executes a snapshot to completion.
+    # Executes the current declarations to completion.
     def call(input = nil, **options) = build.call(input, **options)
-    # Streams a snapshot as StreamEvent objects.
+    # Streams the current declarations as StreamEvent objects.
     def stream(input = nil, **options) = build.stream(input, **options)
-    # Starts a supervised execution from a snapshot.
+    # Starts a supervised execution from the current declarations.
     def start_execution(payload, &block) = build.start_execution(payload, &block)
-    # Exposes a snapshot as a Tool.
+    # Exposes the current declarations as a Tool.
     def as_tool(**options) = build.as_tool(**options)
 
     protected
@@ -258,8 +258,8 @@ module LittleGhost
   #   agent.system_prompt "Answer customer questions clearly."
   #   agent.ask("Where is my order?")
   #
-  # Supported Agent class-DSL calls are recorded and replayed into each
-  # immutable snapshot.
+  # It accepts the same configuration calls as an Agent class. Changing the
+  # builder affects future builds without changing Agents already built.
   class AgentBuilder < AssemblyBuilder
     DECLARATIONS = %i[
       model limits result_schema capture_diagnostics system_template system_prompt
@@ -286,7 +286,7 @@ module LittleGhost
       value.nil? ? assembly_id : assembly_id(value)
     end
 
-    # Records supported Agent class-DSL declarations for the next snapshot.
+    # Applies a supported Agent configuration call to future builds.
     def method_missing(name, *arguments, **keywords, &block)
       return super unless DECLARATIONS.include?(name)
 
@@ -338,7 +338,7 @@ module LittleGhost
   # Builds a Workflow whose Ruby composition block is supplied at runtime.
   # Use a named Workflow subclass's +to_builder+ when the class supplies the
   # composition and runtime configuration supplies its identity or description.
-  # +perform+ supplies the underlying dynamic form for trusted application code.
+  # +perform+ supplies the underlying dynamic form for application code.
   class WorkflowBuilder < AssemblyBuilder
     class << self
       # :nodoc:
@@ -458,19 +458,19 @@ module LittleGhost
       @declarations = []
     end
 
-    %i[node start edge finish max_steps fork join error_edge].each do |name|
+    %i[node start edge finish max_steps max_concurrency error_edge].each do |name|
       define_method(name) do |*arguments, **keywords, &block|
         @mutex.synchronize { @declarations << [name, arguments, keywords, block] }
         self
       end
     end
 
-    # Renders the current validated snapshot as Mermaid flowchart text.
+    # Validates the current declarations and renders them as Mermaid flowchart text.
     def to_mermaid = definition.implementation.to_mermaid
 
     protected
 
-    def snapshot_mutators = super + %i[node start edge finish max_steps fork join error_edge]
+    def snapshot_mutators = super + %i[node start edge finish max_steps max_concurrency error_edge]
 
     def snapshot_state = super.merge(declarations: @declarations.map { |value| value.dup.freeze }.freeze)
 

data/lib/little_ghost/assembly_execution.rb

@@ -193,14 +193,23 @@ module LittleGhost
       policy = normalize_step_policy(policies)
       attempts = []
       usage = Usage.new
+      stream_path = agent_stream_path + [
+        AgentStreamStep.build(
+          assembly_id: self.class.assembly_id,
+          assembly_kind: self.class.assembly_kind,
+          participant:,
+          step_id:,
+          branch_id:
+        )
+      ]
 
       (policy.fetch(:retries) + 1).times do |index|
         attempt_number = index + 1
         started_at = Time.now
         child = if build_options.any? && runtime.respond_to?(:build_agent)
-          runtime.build_agent(reference, run:, **build_options)
+          build_stream_participant(:build_agent, reference, stream_path, **build_options)
         else
-          runtime.build_assembly(reference, run:, **build_options)
+          build_stream_participant(:build_assembly, reference, stream_path, **build_options)
         end
         child_deadline = step_deadline(deadline, policy[:timeout])
         attempt_events = []
@@ -329,6 +338,18 @@ module LittleGhost
       end
     end
 
+    def build_stream_participant(builder_name, reference, stream_path, **options)
+      builder = runtime.method(builder_name)
+      parameters = builder.parameters
+      accepts_path = parameters.any? do |kind, name|
+        kind == :keyrest || (%i[key keyreq].include?(kind) && name == :agent_stream_path)
+      end
+      options[:agent_stream_path] = stream_path if accepts_path
+      child = builder.call(reference, run:, **options)
+      child.bind_agent_stream_path(stream_path) if child.respond_to?(:bind_agent_stream_path)
+      child
+    end
+
     def normalize_step_policy(values)
       self.class.validate_step_policy!(values)
     end

data/lib/little_ghost/code_mode/broker.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module LittleGhost
+  module CodeMode
+    # Keeps tool authorization and execution in the trusted parent process.
+    class Broker
+      # Builds a broker for an Agent's Tool registry. +except+ removes names from
+      # the code-mode catalog. +dispatch+ is a trusted adapter hook used by
+      # custom hosts; ordinary Agent integrations should let the broker dispatch
+      # through +agent+.
+      def initialize(agent: nil, registry: nil, context: RunContext.new, events: [],
+        parent_operation_id: nil, parent_trace_context: nil, except: nil, dispatch: nil, max_calls: nil)
+        @agent = agent
+        @registry = registry || agent&.tool_registry
+        @context = context
+        @events = events
+        @parent_operation_id = parent_operation_id
+        @parent_trace_context = parent_trace_context
+        @except = Array(except).map(&:to_s).freeze
+        @dispatch = dispatch
+        @max_calls = max_calls && Integer(max_calls)
+        @call_count = 0
+        @call_mutex = Mutex.new
+        @delivery_mutex = Mutex.new
+        @presentation_content = []
+        @artifacts = []
+        @fallback_references = []
+        @presentation_budget = Artifacts::PresentationBudget.new
+      end
+
+      # Returns the Tool specifications available to model-authored code.
+      # Excluded Tools, code-mode controls, and subagent controls stay outside
+      # this catalog.
+      def catalog
+        specifications = @registry&.specifications || []
+        specifications.reject do |specification|
+          name = specification.fetch(:name, specification["name"]).to_s
+          tool = @registry.fetch(name)
+          @except.include?(name) || %w[exec wait stop].include?(name) || subagent_control?(tool)
+        end
+      end
+
+      attr_writer :context # :nodoc:
+
+      def bind(context:, events:, parent_operation_id:, parent_trace_context: nil) # :nodoc:
+        @context = context
+        @events = events
+        @parent_operation_id = parent_operation_id
+        @parent_trace_context = parent_trace_context
+        self
+      end
+
+      # Calls an available Tool by model-visible +name+. The returned CallResult
+      # has +id+, decoded +value+, and model-safe +error+ fields. +arguments+
+      # remains untrusted until the ordinary Tool path validates and authorizes
+      # it.
+      def call(name, arguments = {}, id: SecureRandom.uuid)
+        @call_mutex.synchronize do
+          @call_count += 1
+          raise ToolError, "Code-mode tool call budget exceeded" if @max_calls && @call_count > @max_calls
+        end
+        name = String(name).delete_prefix("tools.")
+        available = catalog.any? { |specification| specification.fetch(:name, specification["name"]).to_s == name }
+        raise ToolError, "Tool is not available in code mode: #{name}" unless available
+        raise ToolError, "Tool arguments must be an object" unless arguments.is_a?(Hash)
+
+        execution_result = nil
+        result = if @dispatch
+          dispatched = @dispatch.call(Call.new(id:, name:, arguments:))
+          if dispatched.respond_to?(:presentation_content) && dispatched.respond_to?(:artifacts)
+            record_delivery(dispatched.presentation_content, dispatched.artifacts)
+          end
+          dispatched
+        elsif @agent
+          use = Content::ToolUse.new(id:, name:, input: arguments)
+          emit_brokered_tool_call(use)
+          executed = @agent.dispatch_tools(
+            [use],
+            context: @context,
+            events: @events,
+            parent_operation_id: @parent_operation_id,
+            parent_trace_context: @parent_trace_context
+          ).first
+          record_delivery(executed.presentation_content, executed.artifacts)
+          execution_result = executed.execution_result
+        else
+          tool = @registry.fetch(name)
+          execution = tool.execute(arguments, context: @context)
+          record_delivery(execution.presentation_content, execution.artifacts)
+          return CallResult.new(id:, value: execution.value, error: execution.error? ? execution.content : nil)
+        end
+
+        return result if result.is_a?(CallResult)
+
+        execution_result ||= result
+        content = execution_result.respond_to?(:content) ? execution_result.content : execution_result
+        value = execution_result.respond_to?(:value) ? execution_result.value : decode(content)
+        status = execution_result.respond_to?(:status) ? execution_result.status : :success
+        CallResult.new(id:, value:, error: (content if status == :error))
+      rescue ToolError => error
+        CallResult.new(id:, value: nil, error: error.message)
+      end
+
+      def drain_delivery # :nodoc:
+        @delivery_mutex.synchronize do
+          delivery = [@presentation_content.freeze, @artifacts.freeze, @fallback_references.uniq.freeze]
+          @presentation_content = []
+          @artifacts = []
+          @fallback_references = []
+          @presentation_budget = Artifacts::PresentationBudget.new
+          delivery
+        end
+      end
+
+      private
+
+      def subagent_control?(tool)
+        defined?(Subagents::ControlTool) && tool.is_a?(Subagents::ControlTool)
+      end
+
+      def emit_brokered_tool_call(tool_use)
+        return unless @events.respond_to?(:<<)
+
+        @events << StreamEvent.build(:tool_call_start, index: 0, id: tool_use.id, name: tool_use.name)
+        @events << StreamEvent.build(:tool_call_delta, index: 0, arguments: JSON.generate(tool_use.input))
+        @events << StreamEvent.build(:tool_call_stop, index: 0, tool_use:)
+      end
+
+      def record_delivery(presentations, artifacts)
+        return if presentations.empty? && artifacts.empty?
+
+        @delivery_mutex.synchronize do
+          accepted = @presentation_budget.accept(presentations)
+          @presentation_content.concat(accepted)
+          @artifacts.concat(artifacts)
+          if accepted.empty? && artifacts.any?
+            @fallback_references.concat(artifact_references(artifacts))
+          end
+        end
+      end
+
+      def artifact_references(artifacts)
+        artifacts.filter_map do |artifact|
+          next if artifact.metadata[:complete_result] || artifact.metadata["complete_result"]
+          next unless artifact.reference.is_a?(String) && artifact.bytes
+
+          details = [artifact.media_type, "#{artifact.bytes} bytes"].compact.join(", ")
+          "- #{artifact.reference} (#{details})"
+        end
+      end
+
+      def decode(value)
+        return value unless value.is_a?(String)
+
+        JSON.parse(value)
+      rescue JSON::ParserError
+        value
+      end
+    end
+  end
+end

data/lib/little_ghost/code_mode/catalog.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module CodeMode
+    # Normalizes a trusted Tool catalog for a guest language and rejects names
+    # that would collide or shadow code-mode controls.
+    class Catalog
+      # Frozen normalized Tool definitions in declaration order.
+      attr_reader :definitions
+
+      # Normalizes trusted Tool +specifications+ with +normalize+. Names in
+      # +reserved+ and names that collide after normalization are rejected.
+      def initialize(specifications, normalize:, reserved: %w[exec wait stop])
+        aliases = {}
+        @definitions = Array(specifications).map do |specification|
+          canonical_name = value(specification, :name).to_s
+          name = normalize.call(canonical_name).to_s
+          if reserved.include?(name)
+            raise ConfigurationError, "Code-mode tool name #{canonical_name.inspect} conflicts with reserved tool #{name.inspect}"
+          end
+          if aliases.key?(name)
+            raise ConfigurationError,
+              "Code-mode tool names #{aliases.fetch(name).inspect} and #{canonical_name.inspect} both normalize to #{name.inspect}"
+          end
+
+          aliases[name] = canonical_name
+          {
+            "name" => name.freeze,
+            "canonical_name" => canonical_name.freeze,
+            "description" => value(specification, :description, "").to_s.freeze,
+            "input_schema" => value(specification, :input_schema, {}).freeze,
+            "specification" => specification
+          }.freeze
+        end.freeze
+        @by_name = @definitions.to_h { |definition| [definition.fetch("name"), definition] }.freeze
+      end
+
+      # Returns the normalized definition for +name+.
+      def fetch(name) = @by_name.fetch(name.to_s)
+      # Indicates whether +name+ is present in the catalog.
+      def key?(name) = @by_name.key?(name.to_s)
+
+      private
+
+      def value(specification, key, default = nil)
+        return specification.fetch(key) if specification.key?(key)
+        return specification.fetch(key.to_s) if specification.key?(key.to_s)
+        return default unless default.nil?
+
+        raise KeyError, "key not found: #{key.inspect}"
+      end
+    end
+  end
+end

data/lib/little_ghost/code_mode/engine.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module CodeMode
+    # Adapter contract for a code-mode language.
+    #
+    # An Engine describes the language shown to the model and opens one Session.
+    # Model-authored code must run behind the supplied +sandbox_factory+. The
+    # Broker must remain in the trusted parent process; do not expose it or its
+    # application objects inside the child interpreter.
+    #
+    # LittleGhost may call one registered Engine instance concurrently for
+    # different Agents and RunContexts. Keep mutable program state in the
+    # Session returned by #open_session, not on the Engine.
+    class Engine
+      # Returns the engine's language identifier as a Symbol.
+      def language = raise(AbstractMethodError, "engine must report its language")
+
+      # Returns model-facing instructions for the supplied Tool Catalog. This
+      # method may be called concurrently. Instructions must describe only names
+      # and behavior the Session actually implements.
+      def instructions(catalog:) = raise(AbstractMethodError, "engine must provide instructions")
+
+      # Opens and returns a CodeMode::Session.
+      #
+      # +broker+ is called only from trusted parent code. +sandbox_factory+
+      # creates the Sandbox that contains model-authored execution. +limits+ is
+      # the application's mapping, passed through unchanged. A custom Engine
+      # must normalize keys and values, validate supported settings, and merge
+      # its own safe defaults. The Session owns every Workspace, Sandbox,
+      # process, thread, and channel it creates. This method may be called
+      # concurrently; each call must return an independent Session.
+      def open_session(broker:, sandbox_factory:, limits:) = raise(AbstractMethodError, "engine must open a session")
+
+      private
+
+      def normalize_limits(limits, defaults:)
+        configured = limits.to_h.transform_keys(&:to_sym)
+        unsupported = configured.keys - defaults.keys
+        unless unsupported.empty?
+          names = unsupported.sort_by(&:to_s).map(&:inspect).join(", ")
+          raise ArgumentError, "unsupported code-mode limits: #{names}"
+        end
+
+        defaults.merge(configured)
+      end
+
+      def allow_subprocesses_for(sandbox)
+        capabilities = sandbox.capabilities
+        return true if capabilities.supports?(:process_tree_ownership)
+        return false if capabilities.supports?(:process_spawn_denial)
+        return true if capabilities.isolation == :none
+
+        raise CapabilityError, "code mode requires owned subprocesses or enforced subprocess denial"
+      end
+    end
+  end
+end

data/lib/little_ghost/code_mode/javascript/catalog.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LittleGhost
+  module CodeMode
+    class Javascript::Catalog < CodeMode::Catalog # :nodoc: all
+      IDENTIFIER_CHARACTER = /[^A-Za-z0-9_$]/
+      RESERVED_NAMES = %w[exec wait stop].freeze
+
+      def initialize(specifications)
+        super(specifications, normalize: method(:normalize), reserved: RESERVED_NAMES)
+      end
+
+      def host_definitions
+        @host_definitions ||= @definitions.map do |definition|
+          definition.slice("name", "description", "input_schema").freeze
+        end.freeze
+      end
+
+      def declarations
+        body = @definitions.map do |definition|
+          description = TypeScript.comment(definition.fetch("description"))
+          signature = "#{definition.fetch("name")}(args: " \
+            "#{TypeScript.render(definition.fetch("input_schema"))}): Promise<unknown>;"
+          [description, signature].compact.join("\n")
+        end.join("\n")
+        "declare const tools: {\n#{TypeScript.indent(body)}\n};"
+      end
+
+      def self.normalize(name)
+        normalized = name.to_s.gsub(IDENTIFIER_CHARACTER, "_")
+        normalized = "_#{normalized}" unless normalized.match?(/\A[A-Za-z_$]/)
+        normalized = "_then" if normalized == "then"
+        normalized
+      end
+
+      def normalize(name) = self.class.normalize(name)
+
+      module TypeScript
+        module_function
+
+        def render(schema)
+          schema = schema.to_h.transform_keys(&:to_s)
+          return JSON.generate(schema.fetch("const")) if schema.key?("const")
+          return schema.fetch("enum").map { |value| JSON.generate(value) }.join(" | ") if schema["enum"]
+
+          alternatives = schema["anyOf"] || schema["oneOf"]
+          return alternatives.map { |child| render(child) }.join(" | ") if alternatives
+          if schema["allOf"]
+            return schema.fetch("allOf").map do |child|
+              value = render(child)
+              value.include?(" | ") ? "(#{value})" : value
+            end.join(" & ")
+          end
+
+          types = Array(schema["type"])
+          return types.map { |type| render(schema.merge("type" => type)) }.uniq.join(" | ") if types.length > 1
+
+          case types.first
+          when "object" then object(schema)
+          when "array" then array(schema)
+          when "string" then "string"
+          when "integer", "number" then "number"
+          when "boolean" then "boolean"
+          when "null" then "null"
+          else
+            schema.key?("properties") ? object(schema) : "unknown"
+          end
+        end
+
+        def object(schema)
+          required = Array(schema["required"])
+          properties = schema.fetch("properties", {}).map do |name, child|
+            property = identifier(name) ? name : JSON.generate(name)
+            description = comment(child.to_h["description"] || child.to_h[:description])
+            optional = "?" unless required.include?(name.to_s)
+            line = "#{property}#{optional}: #{render(child)};"
+            [description, line].compact.join("\n")
+          end
+          additional = schema["additionalProperties"]
+          if additional == true
+            properties << "[key: string]: unknown;"
+          elsif additional.is_a?(Hash)
+            properties << "[key: string]: #{render(additional)};"
+          end
+          return "Record<string, never>" if properties.empty? && additional == false
+          return "Record<string, unknown>" if properties.empty?
+
+          "{\n#{indent(properties.join("\n"))}\n}"
+        end
+
+        def array(schema)
+          items = schema["items"]
+          return "unknown[]" unless items
+          return "[#{items.map { |child| render(child) }.join(", ")}]" if items.is_a?(Array)
+
+          "Array<#{render(items)}>"
+        end
+
+        def comment(value)
+          return if value.to_s.empty?
+
+          sanitized = value.to_s.gsub("*/", "*\\/").gsub(/\s+/, " ").strip
+          "/** #{sanitized} */"
+        end
+
+        def indent(value)
+          value.lines.map { |line| "  #{line}" }.join
+        end
+
+        def identifier(value)
+          value.to_s.match?(/\A[A-Za-z_$][A-Za-z0-9_$]*\z/)
+        end
+      end
+    end
+  end
+end