pikuri-core 0.0.3 → 0.0.4

data/lib/pikuri/tool/parameters.rb

@@ -133,6 +133,38 @@ module Pikuri
         add(name, 'boolean', description, required: false)
       end
 
+      # Add a required +enum+ property — a +string+ field constrained
+      # to one of a fixed set of values. Emits JSON-Schema +enum+
+      # alongside +type: 'string'+, which the LLM treats as a closed
+      # choice. Validation rejects any string outside the set with an
+      # LLM-actionable error message listing the allowed values.
+      #
+      # @param name [Symbol] property name
+      # @param description [String] human-readable description shown to the LLM
+      # @param values [Array<String>] non-empty list of allowed values;
+      #   each entry must be a non-empty String. The list is +dup+'d
+      #   and frozen at insertion so callers can't mutate it later.
+      # @return [self]
+      # @raise [ArgumentError] if +values+ is not a non-empty Array of
+      #   non-empty Strings (build-time check — surfaces as a host-side
+      #   bug rather than an LLM-facing validation error)
+      def required_enum(name, description, values:)
+        add_enum(name, description, values, required: true)
+      end
+
+      # Add an optional +enum+ property. See {#required_enum} for the
+      # +values+ contract and validation behavior.
+      #
+      # @param name [Symbol] property name
+      # @param description [String] human-readable description shown to the LLM
+      # @param values [Array<String>] non-empty list of allowed values
+      # @return [self]
+      # @raise [ArgumentError] if +values+ is not a non-empty Array of
+      #   non-empty Strings
+      def optional_enum(name, description, values:)
+        add_enum(name, description, values, required: false)
+      end
+
       # Schema in OpenAI JSON-Schema shape.
       #
       # @return [Hash] +{type: 'object', properties: {...}, required: [...]}+
@@ -168,12 +200,15 @@ module Pikuri
         @properties.each do |name, schema|
           if symbolized.key?(name)
             begin
-              result[name] = coerce(symbolized[name], schema[:type])
+              coerced = coerce(symbolized[name], schema[:type])
+              raise CoercionError, enum_message(schema[:enum], coerced) if schema[:enum] && !schema[:enum].include?(coerced)
+
+              result[name] = coerced
             rescue CoercionError => e
               errors << "Parameter `#{name}` #{e.message}."
             end
           elsif @required.include?(name.to_s)
-            errors << "Missing required parameter `#{name}` (#{schema[:type]}): #{schema[:description]}"
+            errors << missing_required_message(name, schema)
           end
         end
 
@@ -195,6 +230,22 @@ module Pikuri
         self
       end
 
+      def add_enum(name, description, values, required:)
+        unless values.is_a?(Array) && !values.empty? &&
+               values.all? { |v| v.is_a?(String) && !v.empty? }
+          raise ArgumentError,
+                "values: must be a non-empty Array of non-empty Strings, got #{values.inspect}"
+        end
+
+        @properties[name] = {
+          type: 'string',
+          enum: values.dup.freeze,
+          description: description
+        }
+        @required << name.to_s if required
+        self
+      end
+
       # Coerce +value+ to a Ruby value matching the JSON-Schema +type+,
       # returning the coerced value. Raises {CoercionError} on failure.
       def coerce(value, type)
@@ -284,6 +335,15 @@ module Pikuri
         "must be #{article} #{type} (got #{value.class}: #{value.inspect})"
       end
 
+      def enum_message(values, got)
+        "must be one of #{values.map { |v| "`#{v}`" }.join(', ')} (got String: #{got.inspect})"
+      end
+
+      def missing_required_message(name, schema)
+        enum_part = schema[:enum] ? ", one of: #{schema[:enum].map { |v| "`#{v}`" }.join(', ')}" : ''
+        "Missing required parameter `#{name}` (#{schema[:type]}#{enum_part}): #{schema[:description]}"
+      end
+
       def unknown_key_error(unknown)
         suggestion = DidYouMean::SpellChecker
                      .new(dictionary: @properties.keys.map(&:to_s))
@@ -305,7 +365,8 @@ module Pikuri
           'Expected schema:',
           *@properties.map { |name, prop|
             req = @required.include?(name.to_s) ? 'required' : 'optional'
-            "  - `#{name}` (#{prop[:type]}, #{req}): #{prop[:description]}"
+            enum_part = prop[:enum] ? ", one of: #{prop[:enum].map { |v| "`#{v}`" }.join(', ')}" : ''
+            "  - `#{name}` (#{prop[:type]}, #{req}#{enum_part}): #{prop[:description]}"
           }
         ].join("\n")
       end

data/lib/pikuri/tool.rb

@@ -58,8 +58,13 @@ module Pikuri
     attr_reader :parameters
 
     # @return [Proc] callable invoked once arguments have been validated;
-    #   receives validated keyword arguments and returns a +String+
-    #   observation
+    #   receives validated keyword arguments and returns the observation.
+    #   The usual return is a +String+; tools that want to deliver
+    #   multimodal observations (e.g. {Pikuri::Workspace::Read} on a
+    #   PNG) may instead return a +RubyLLM::Content+ with attachments,
+    #   which +RubyLLM::Chat#handle_tool_calls+ accepts via its
+    #   +content_like?+ check and the per-provider Media formatters turn
+    #   into the right image / document blocks inside +tool_result+.
     attr_reader :execute
 
     # @param name [String] function name advertised to the LLM
@@ -67,9 +72,10 @@ module Pikuri
     #   to decide when to call the tool
     # @param parameters [Tool::Parameters] declared schema
     # @param execute [Proc] callable invoked with validated keyword arguments
-    #   that returns a +String+ observation. Recoverable failures should be
-    #   returned as +"Error: <message>"+ Strings rather than raised — see
-    #   "Error handling convention" above.
+    #   that returns either a +String+ observation or a +RubyLLM::Content+
+    #   (for multimodal observations — see {#execute}). Recoverable failures
+    #   should be returned as +"Error: <message>"+ Strings rather than raised
+    #   — see "Error handling convention" above.
     # @return [Tool]
     def initialize(name:, description:, parameters:, execute:)
       @name = name
@@ -84,8 +90,10 @@ module Pikuri
     # to the LLM as the next observation; everything else bubbles up.
     #
     # @param args [Hash] raw arguments supplied by the LLM
-    # @return [String] tool observation, or +"Error: ..."+ on validation
-    #   failure
+    # @return [String, RubyLLM::Content] tool observation. Validation
+    #   failures always come back as +"Error: ..."+ Strings; the success
+    #   shape is whatever the +execute+ Proc returns (typically a String,
+    #   or a +RubyLLM::Content+ for multimodal observations).
     def run(args)
       validated = @parameters.validate(args)
       @execute.call(**validated)

data/lib/pikuri/version.rb

@@ -6,5 +6,5 @@ module Pikuri
   # additions to the public surface (+Pikuri::Tool+ / +Pikuri::Agent+ /
   # listeners / bundled tools), major for breaking changes to that
   # surface or to the +bin/pikuri-*+ CLIs.
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pikuri-core
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Martin Vysny
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-22 00:00:00.000000000 Z
+date: 2026-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dentaku
@@ -199,6 +199,7 @@ files:
 - lib/pikuri/agent/listener/token_log.rb
 - lib/pikuri/agent/listener_list.rb
 - lib/pikuri/agent/synthesizer.rb
+- lib/pikuri/file_type.rb
 - lib/pikuri/subprocess.rb
 - lib/pikuri/tool.rb
 - lib/pikuri/tool/calculator.rb
@@ -214,7 +215,6 @@ files:
 - lib/pikuri/tool/search/exa.rb
 - lib/pikuri/tool/search/rate_limiter.rb
 - lib/pikuri/tool/search/result.rb
-- lib/pikuri/tool/sub_agent.rb
 - lib/pikuri/tool/web_scrape.rb
 - lib/pikuri/tool/web_search.rb
 - lib/pikuri/url_cache.rb

data/lib/pikuri/tool/sub_agent.rb

@@ -1,150 +0,0 @@
-# frozen_string_literal: true
-
-module Pikuri
-  class Tool
-    # The +sub_agent+ tool, expressed as a {Tool} subclass: instantiating
-    # +Tool::SubAgent.new(parent_agent)+ produces a tool whose
-    # {Tool#to_ruby_llm_tool} wiring is identical to any bundled tool's,
-    # so ruby_llm sees nothing special about it. When the model calls it,
-    # the closure inside +execute+ spawns a fresh {Agent} that runs its
-    # own Thought / Tool-call / Observation loop on a clean message
-    # history, then returns only the sub-agent's final assistant message
-    # back as the parent's next observation.
-    #
-    # The sub-agent reuses the parent's +transport+, +system_prompt+,
-    # +context_window_cap+, and +name+ (as its hierarchical prefix), so
-    # it shares the same persona, hits the same server, and inherits the
-    # same context-window cap without re-probing. Its tool list is a
-    # snapshot of the parent's {Agent#tools} taken at construction —
-    # {Agent#allow_sub_agent} only appends the sub-agent tool to its own
-    # +@tools+ *after* this snapshot, so the sub-agent's tool list never
-    # contains itself (recursion guard).
-    #
-    # Its listener list comes from the parent's {Agent#listeners} via
-    # {Agent::ListenerList#for_sub_agent}, which forwards to each
-    # listener's own +for_sub_agent+ hook: +Terminal+ swaps to a padded
-    # fresh instance, +TokenLog+ resets its snapshot, and listeners
-    # without the hook ({Agent::Listener::InMemoryEventList}, …) are
-    # shared by reference so structured capture flows continuously.
-    #
-    # Controls are derived per the per-control rule: a fresh
-    # {Agent::Control::StepLimit} at the new cap (mutable counter is
-    # per-chat), the same {Agent::Control::Cancellable} shared by
-    # reference (one +cancel!+ stops the whole tree), and no
-    # {Agent::Control::Interloper} (the host has no handle to
-    # sub-agents).
-    #
-    # All parent state is captured by value at construction — the closure
-    # does not chase +parent_agent+ mutations later. The one piece of
-    # mutable state is a monotonic counter used to generate sub-agent ids:
-    # +"sub_agent 0"+, +"sub_agent 1"+, ... at the top level; nested
-    # children of +"sub_agent 0"+ are +"sub_agent 0_0"+, +"sub_agent 0_1"+,
-    # ... — the +"sub_agent "+ prefix appears once at the top and the
-    # underscore-separated counter chain records depth.
-    class SubAgent < Tool
-      # Description shown to the LLM. Follows the opencode-shape (summary
-      # + +Usage:+ bullets) prescribed by the project's tool-description
-      # convention.
-      #
-      # @return [String]
-      DESCRIPTION = <<~DESC
-        Delegate a self-contained task to a fresh sub-agent that runs its own Thought / Tool-call / Observation loop on a clean conversation, returning only its final assistant message.
-
-        Usage:
-        - Use to isolate side-quests — research, multi-step lookups, exploratory tool use — so intermediate observations do not clutter your own context.
-        - The sub-agent has your tools minus `sub_agent` itself, so it cannot recurse.
-        - It shares your system prompt — persona, tool-use conventions, and output format carry over. Do NOT re-explain who you are or how to use tools.
-        - It cannot see your conversation. Put ALL task-specific context inside `task`; the sub-agent has zero memory of what came before.
-      DESC
-
-      # @param parent_agent [Agent] the calling agent. Read for its
-      #   {Agent#transport}, {Agent#system_prompt}, {Agent#tools},
-      #   {Agent#listeners}, {Agent#step_limit}, {Agent#cancellable},
-      #   {Agent#context_window_cap}, {Agent#name}, and
-      #   {Agent#extensions} (so the sub-agent inherits and re-binds
-      #   the parent's extension list).
-      # @param max_steps [Integer] step budget for each sub-agent run,
-      #   used to construct the sub-agent's own
-      #   {Agent::Control::StepLimit}.
-      # @return [SubAgent]
-      def initialize(parent_agent, max_steps: 10)
-        transport         = parent_agent.transport
-        system_prompt     = parent_agent.system_prompt
-        sub_tools         = parent_agent.tools.dup
-        listeners         = parent_agent.listeners
-        parent_step_limit = parent_agent.step_limit
-        parent_cancel     = parent_agent.cancellable
-        context_window    = parent_agent.context_window_cap
-        parent_name       = parent_agent.name
-        streaming         = parent_agent.streaming
-        # Parent's extension list, captured at SubAgent construction
-        # so spawned sub-agents share the *same* extension instances
-        # (configure has already run on the parent — the resulting
-        # tools / snippets / listeners are inherited verbatim via
-        # the kwargs above). Each inherited extension's +bind+ fires
-        # inside the sub-agent's +Agent#initialize+ — that's how
-        # MCP's per-agent connect tool ends up keyed to the
-        # sub-agent rather than the parent, while still sharing the
-        # parent's live MCP clients through the extension instance.
-        # See IDEAS.md §"Sub-agent inheritance — configure-once,
-        # bind-per-agent".
-        inherited_exts    = parent_agent.extensions
-        sub_counter       = 0
-
-        super(
-          name: 'sub_agent',
-          description: DESCRIPTION,
-          parameters: Parameters.build { |p|
-            p.required_string :task,
-                              'Self-contained instructions for the sub-agent, ' \
-                              'e.g. "Find the populations of Reykjavik and ' \
-                              'Helsinki in 2024 and report both numbers." ' \
-                              'It has no access to the parent conversation, ' \
-                              'so include all necessary context.'
-          },
-          execute: lambda { |task:|
-            idx = sub_counter
-            sub_counter += 1
-            sub_name = parent_name.empty? ? "sub_agent #{idx}" : "#{parent_name}_#{idx}"
-            sub_listeners = listeners.for_sub_agent(name: sub_name)
-
-            # All inherited state is seeded through the Configurator
-            # block — tools and listeners via add_tools / add_listeners,
-            # extensions via inherit_extensions which retains them for
-            # the bind sweep without re-running configure (the parent
-            # already drove that and the resulting system-prompt
-            # snippets are inherited verbatim through +system_prompt+).
-            sub = Agent.new(
-              transport: transport,
-              system_prompt: system_prompt,
-              step_limit: parent_step_limit&.for_sub_agent(max_steps: max_steps),
-              cancellable: parent_cancel&.for_sub_agent,
-              context_window: context_window,
-              name: sub_name,
-              streaming: streaming
-            ) do |c|
-              c.add_tools(sub_tools)
-              c.add_listeners(sub_listeners)
-              c.inherit_extensions(inherited_exts)
-            end
-            begin
-              sub.run_loop(user_message: task)
-              sub.last_assistant_content
-            ensure
-              # The sub-agent borrows the parent's MCP clients via
-              # the shared {Mcp::Extension} instance; it doesn't own
-              # them. {#close} still fires its own +on_close+ list
-              # (empty for a sub-agent — no extensions registered
-              # any handlers via the inherited path, since they only
-              # re-bind here, not re-configure), so this is a no-op
-              # today. Calling +#close+ anyway means any future
-              # sub-agent-owned resource gets released without
-              # revisiting this site. See {Agent#close}.
-              sub.close
-            end
-          }
-        )
-      end
-    end
-  end
-end