pikuri 0.0.1

data/lib/pikuri/tool/workspace.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Pikuri
+  class Tool
+    # Defines which paths the agent can see and write to. Subclass and
+    # implement {#cwd}, {#resolve_for_read}, and {#resolve_for_write}.
+    # Returned Pathnames are absolute, post-symlink-resolution.
+    #
+    # == Read-set vs. write-set
+    #
+    # The two resolve methods exist because a future workspace may admit
+    # paths for reading that it refuses for writing — e.g. a multi-root
+    # workspace where +~/.claude/skills+ is readable but only the project
+    # CWD is writable. For v1's {Cwd} the two methods are the same: read-
+    # set and write-set are both the CWD subtree.
+    #
+    # == Existence is not the workspace's concern
+    #
+    # +resolve_for_read('foo.rb')+ succeeds (returns a +Pathname+) even if
+    # +foo.rb+ doesn't exist; the caller ({Tool::Read}) errors with
+    # file-not-found when it tries to open it. +resolve_for_write+
+    # tolerates entirely non-existent paths (Write can create
+    # +lib/new/dir/foo.rb+ even when +lib/new/+ doesn't exist) — the
+    # caller is responsible for any +mkdir_p+ before writing. This split
+    # keeps the workspace narrowly responsible for *containment*, not for
+    # filesystem-state checks.
+    #
+    # == Future extensions (out of scope for v1)
+    #
+    # * Multi-root workspace: +~/.claude/skills+ readable, CWD writable.
+    # * +Tool::Workspace::ALLOW_ALL+: no restriction, planned for Docker /
+    #   dev-container mode.
+    class Workspace
+      # Raised for any path that resolves outside the workspace. Recoverable
+      # at the tool layer — tools rescue this and emit +"Error: ..."+
+      # observations so the LLM can self-correct on the next turn.
+      class Error < StandardError; end
+
+      # Project anchor: where shells run, where modifications are made.
+      # For {Cwd} this is the constructor's +root:+ (after +realpath+);
+      # a future +ALLOW_ALL+ would return the user's invocation
+      # directory.
+      #
+      # @return [Pathname]
+      # @raise [NotImplementedError] in the abstract base
+      def cwd
+        raise NotImplementedError, "#{self.class}#cwd must be implemented"
+      end
+
+      # Resolve a user-supplied path against the workspace's read-set.
+      # Returned Pathname is absolute and may not exist on disk; the
+      # caller validates existence separately.
+      #
+      # @param path [String] user-supplied path, absolute or relative
+      # @return [Pathname]
+      # @raise [Error] if the resolved path falls outside the read-set
+      # @raise [NotImplementedError] in the abstract base
+      def resolve_for_read(path)
+        raise NotImplementedError, "#{self.class}#resolve_for_read must be implemented"
+      end
+
+      # Resolve a user-supplied path against the workspace's write-set.
+      # Same shape as {#resolve_for_read}; semantically distinct so a
+      # future workspace can permit reading paths it refuses to write.
+      #
+      # @param path [String]
+      # @return [Pathname]
+      # @raise [Error] if the resolved path falls outside the write-set
+      # @raise [NotImplementedError] in the abstract base
+      def resolve_for_write(path)
+        raise NotImplementedError, "#{self.class}#resolve_for_write must be implemented"
+      end
+
+      # Locks read+write to a single subtree (the +root:+ passed at
+      # construction, with symlinks resolved). +cwd+ equals the root.
+      #
+      # == Containment algorithm
+      #
+      # +#resolve+ walks up the input path to its deepest existing
+      # ancestor, +realpath+'s that ancestor (resolving any symlinks in
+      # the existing portion), then verifies the resolved anchor is
+      # +@root+ or a descendant. Four cases the algorithm must handle:
+      #
+      # 1. +lib/foo.rb+ (exists) → +existing+ = full path, +anchor+ in
+      #    root → returns the realpath'd file.
+      # 2. +lib/new/dir/foo.rb+ (intermediates missing) → walks up to
+      #    +@root/lib+, +anchor+ in root → returns the intended new path
+      #    (caller +mkdir_p+s the parent before writing).
+      # 3. +lib/../../etc/passwd+ (+..+ escape) → +cleanpath+ collapses
+      #    +..+ syntactically, walks land outside +@root+ → +Error+.
+      # 4. +link/foo.rb+ where +link → /etc+ (symlink escape) → walks to
+      #    +link+ (which exists), +realpath+ resolves through the
+      #    symlink to +/etc+, outside +@root+ → +Error+.
+      #
+      # Pure lexical normalization (+cleanpath+ + prefix check) catches
+      # cases 1–3 but misses case 4. The walk-up step adds the
+      # +realpath+ pass on the existing prefix, closing that gap.
+      class Cwd < Workspace
+        # @param root [String, Pathname] absolute (or working-directory-
+        #   relative) path to anchor the workspace at. +realpath+'d once
+        #   so subsequent comparisons happen in canonical form.
+        # @raise [Errno::ENOENT] if +root+ does not exist; surfaces
+        #   immediately so misconfigured callers fail loudly.
+        def initialize(root:)
+          @root = Pathname.new(root).realpath
+        end
+
+        # @return [Pathname]
+        def cwd
+          @root
+        end
+
+        # @param path [String]
+        # @return [Pathname]
+        # @raise [Error]
+        def resolve_for_read(path)
+          resolve(path)
+        end
+
+        # @param path [String]
+        # @return [Pathname]
+        # @raise [Error]
+        def resolve_for_write(path)
+          resolve(path)
+        end
+
+        private
+
+        # See class header for the algorithm rationale.
+        def resolve(path)
+          pn = Pathname.new(path)
+          pn = @root + pn unless pn.absolute?
+          cleaned = pn.cleanpath
+
+          existing = cleaned
+          existing = existing.parent until existing.exist? || existing.parent == existing
+          anchor = existing.realpath
+
+          unless anchor == @root || anchor.to_s.start_with?(@root.to_s + File::SEPARATOR)
+            raise Error, "path '#{path}' is outside the workspace '#{@root}'"
+          end
+
+          anchor + cleaned.relative_path_from(existing)
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/tool/write.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Pikuri
+  class Tool
+    # The +write+ tool, expressed as a {Tool} subclass: instantiating
+    # +Tool::Write.new(workspace: ws, confirmer: c)+ 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. Same shape as
+    # {Tool::SubAgent} and {Tool::Read} — workspace and confirmer are
+    # captured by the +execute+ closure at construction.
+    #
+    # == Policy
+    #
+    # Three branches based on the on-disk state of +path+:
+    #
+    # 1. *New file* — write, no prompt.
+    # 2. *Existing file, identical content* — return an +"Error: ..."+
+    #    no-op observation *before* invoking the confirmer; don't ask the
+    #    user to approve a write that wouldn't change the file. Comparison
+    #    is byte-strict, in BINARY encoding (trailing-newline-only
+    #    differences trigger the confirm path; encoding tags can't make
+    #    equal bytes compare unequal).
+    # 3. *Existing file, content differs* — confirm with
+    #    +"OK to overwrite <path>: <old> → <new> bytes?"+ via {Confirmer};
+    #    on yes, write. On no, return a decline-Error observation.
+    #
+    # == Why ask-on-overwrite (Edit doesn't)
+    #
+    # Edit's +old_string+ argument is an implicit read-check: the model
+    # can't write a correct +old_string+ without having read the file, so
+    # blast radius is bounded by what the model actually knows about file
+    # state. Write has no such check, so a hallucinated 500-line +content+
+    # could clobber unread work. The confirmation prompt guards exactly
+    # the gap Edit's argument shape already covers.
+    #
+    # == Side effects
+    #
+    # Parent directories are created (+FileUtils.mkdir_p+) before the
+    # write — matches the +git add lib/new/dir/foo.rb+ mental model and
+    # mirrors opencode's and pi's behavior. Edge case: +mkdir_p+ succeeds
+    # but the write fails; an empty directory is left behind. Accepted
+    # for v1 — users have version control.
+    #
+    # No atomic temp-file+rename. Plain +File.write+, same as opencode and
+    # pi. The crash-safety story is "the user has git".
+    class Write < Tool
+      # Description shown to the LLM. Follows the opencode-shape (summary
+      # + +Usage:+ bullets) prescribed by the project's tool-description
+      # convention. Per-parameter constraints live in the parameter
+      # descriptions; the +Usage:+ bullets are for "when do I pick this?
+      # how does it chain with other tools?".
+      #
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        Write a file to the workspace, creating parent directories as needed.
+
+        Usage:
+        - Use for new files or full-file rewrites; for partial changes use `edit` instead.
+        - Overwriting an existing file requires user confirmation; identical content is rejected as a no-op error — if you see that error, re-read the file rather than trying again.
+        - Parent directories are created automatically (mkdir -p).
+        - Writes the exact bytes supplied: no trailing-newline normalization, no encoding conversion.
+        - Paths outside the workspace are refused.
+      DESC
+
+      # @param workspace [Tool::Workspace] captured for path resolution;
+      #   all writes route through +workspace.resolve_for_write+.
+      # @param confirmer [Tool::Confirmer] consulted before any overwrite
+      #   of an existing file with non-identical content.
+      # @return [Write]
+      def initialize(workspace:, confirmer:)
+        super(
+          name: 'write',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :path,
+                              'Path to the file to write. Relative paths ' \
+                              'resolve against the workspace root, e.g. ' \
+                              '"lib/foo.rb".'
+            p.required_string :content,
+                              'Full contents to write to the file, e.g. ' \
+                              '"class Foo\nend\n".'
+          },
+          execute: ->(path:, content:) {
+            Write.write(workspace: workspace, confirmer: confirmer, path: path, content: content)
+          }
+        )
+      end
+
+      # Resolve +path+ against +workspace+, apply the three-branch policy
+      # (new / identical / differs), and return either a success
+      # observation or an +"Error: ..."+ observation.
+      #
+      # @param workspace [Tool::Workspace]
+      # @param confirmer [Tool::Confirmer]
+      # @param path [String] raw path as supplied by the LLM
+      # @param content [String] bytes to write
+      # @return [String] tool observation
+      def self.write(workspace:, confirmer:, path:, content:)
+        resolved = workspace.resolve_for_write(path)
+
+        if resolved.exist?
+          return "Error: #{path} is a directory" if resolved.directory?
+
+          existing = read_for_compare(resolved, path)
+
+          if existing == content.b
+            return "Error: #{path} already contains exactly this content — " \
+                   'no write needed. If you intended a change, re-read the ' \
+                   'file and try again.'
+          end
+
+          prompt = "OK to overwrite #{path}: #{existing.bytesize} → #{content.bytesize} bytes? (y/n)"
+          return "Error: user declined the write to #{path}." unless confirmer.confirm?(prompt: prompt)
+
+          write_bytes(resolved, content)
+          "Updated #{path} (#{existing.bytesize} → #{content.bytesize} bytes)"
+        else
+          write_bytes(resolved, content)
+          "Created #{path} (#{content.bytesize} bytes)"
+        end
+      rescue Tool::Workspace::Error, Error => e
+        "Error: #{e.message}"
+      rescue Errno::EACCES => e
+        "Error: cannot write #{path}: #{e.message}"
+      end
+
+      # Internal-only signal for LLM-actionable preconditions that Write
+      # detects before any filesystem mutation — today, "existing file is
+      # unreadable so the identical-content check can't run". Mirrors
+      # {Tool::Workspace::Error} in shape: caught by {.write}'s outer
+      # rescue and rendered as a +"Error: ..."+ observation. The class
+      # is +private_constant+ to keep it from leaking out as a public
+      # exception type; callers should never +rescue+ this directly.
+      class Error < StandardError; end
+      private_constant :Error
+
+      # Read the existing file in BINARY mode so the equality check is
+      # purely byte-wise. Raises {Error} on +Errno::EACCES+ so {.write}'s
+      # outer rescue can render a specific "cannot read for overwrite
+      # check" message — without this conversion the bottom +Errno::EACCES+
+      # rescue would mislabel the read-side problem as "cannot write".
+      #
+      # @param resolved [Pathname]
+      # @param path [String] original path for the error message
+      # @return [String]
+      # @raise [Error] when the file exists but isn't readable
+      def self.read_for_compare(resolved, path)
+        resolved.binread
+      rescue Errno::EACCES => e
+        raise Error, "cannot read #{path} for overwrite check: #{e.message}"
+      end
+      private_class_method :read_for_compare
+
+      # +mkdir_p+ the parent, then write. Split out so both the create-
+      # and overwrite-branches can reuse it without duplicating the
+      # +mkdir_p+ call.
+      #
+      # @param resolved [Pathname]
+      # @param content [String]
+      # @return [void]
+      def self.write_bytes(resolved, content)
+        FileUtils.mkdir_p(resolved.dirname)
+        resolved.write(content)
+      end
+      private_class_method :write_bytes
+    end
+  end
+end

data/lib/pikuri/tool.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+
+module Pikuri
+  # A tool the LLM can request via OpenAI-style tool calling.
+  #
+  # {Tool} is a plain value object: +name+, +description+, +parameters+,
+  # and an +execute+ Proc that produces the observation. Pikuri's own
+  # code talks to this surface (the bundled tools, the sub-agent factory,
+  # the +Agent+ constructor); the conversion to ruby_llm's runtime shape
+  # happens at exactly one named seam — {#to_ruby_llm_tool} — which the
+  # +Agent+ calls when wiring tools into the underlying +RubyLLM::Chat+.
+  #
+  # Bundled tool implementations live under +lib/tool/+ and are required
+  # explicitly by the scripts that use them; +lib/tool.rb+ itself only
+  # introduces the {Tool} class and {Tool::Parameters} machinery.
+  #
+  # == Validation ordering
+  #
+  # Pikuri's {Parameters#validate} — DidYouMean suggestions, type coercion,
+  # all-errors-collected — is what the LLM must see when it emits bad
+  # arguments, not ruby_llm's keyword-presence checker. The synthetic
+  # class produced by {#to_ruby_llm_tool} defines +execute(**args)+: the
+  # keyrest signature makes +RubyLLM::Tool#validate_keyword_arguments+
+  # no-op (it bails out at the +accepts_extra_keywords+ check), so
+  # pikuri's validator runs inside {#run} before any user code does.
+  #
+  # == Error handling convention
+  #
+  # Tools split failures into two buckets:
+  #
+  # * *Recoverable* failures — anything the LLM can react to by retrying with
+  #   different inputs (bad arguments, HTTP 4xx/5xx, network blips, search
+  #   provider rate-limits, division by zero in the calculator, ...). These
+  #   come back as a +"Error: <message>"+ String and become the next
+  #   observation; the model sees them and self-corrects on the following
+  #   turn instead of crashing the agent loop.
+  # * *Bugs* in pikuri's own code (parser regressions, schema misuse,
+  #   misconfigured clients, ...). These keep raising. The LLM cannot fix
+  #   them; a human needs to.
+  #
+  # Argument-validation failures from {Parameters#validate} are caught by
+  # {#run} and turned into +"Error: ..."+ observations. The +execute+ Proc
+  # owns the rest — it should follow the same convention internally for
+  # tool-specific recoverable failures, and let bugs raise.
+  class Tool
+    # @return [String] function name advertised to the LLM
+    attr_reader :name
+
+    # @return [String] human-readable description used by the LLM to decide
+    #   when to call the tool
+    attr_reader :description
+
+    # @return [Tool::Parameters] declared schema; validates incoming
+    #   arguments and serializes to the JSON Schema shape advertised to the
+    #   LLM
+    attr_reader :parameters
+
+    # @return [Proc] callable invoked once arguments have been validated;
+    #   receives validated keyword arguments and returns a +String+
+    #   observation
+    attr_reader :execute
+
+    # @param name [String] function name advertised to the LLM
+    # @param description [String] human-readable description used by the LLM
+    #   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.
+    # @return [Tool]
+    def initialize(name:, description:, parameters:, execute:)
+      @name = name
+      @description = description
+      @parameters = parameters
+      @execute = execute
+    end
+
+    # Validate +args+ against {#parameters} and forward them as keyword
+    # arguments to {#execute}. Validation failures are caught and rendered
+    # as +"Error: <message>"+ Strings so the agent loop can feed them back
+    # 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
+    def run(args)
+      validated = @parameters.validate(args)
+      @execute.call(**validated)
+    rescue Tool::Parameters::ValidationError => e
+      "Error: #{e.message}"
+    end
+
+    # Build a synthetic +RubyLLM::Tool+ subclass that wraps this Tool. The
+    # subclass is what +RubyLLM::Chat#with_tool+ accepts: ruby_llm
+    # instantiates it (+tool.new+) and routes tool calls through
+    # +instance.call(args)+, which lands in +#execute(**args)+ and
+    # delegates back to {#run} on this instance.
+    #
+    # @return [Class] anonymous +RubyLLM::Tool+ subclass
+    def to_ruby_llm_tool
+      pikuri_tool = self
+      schema      = @parameters.to_h
+      tool_name   = @name
+      tool_desc   = @description
+
+      Class.new(RubyLLM::Tool) do
+        description(tool_desc)
+        params(schema)
+
+        define_singleton_method(:name) { tool_name }
+        define_method(:execute) { |**args| pikuri_tool.run(args) }
+      end
+    end
+  end
+end

data/lib/pikuri/url_cache.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+
+module Pikuri
+  # On-disk cache for string-keyed text payloads. Used by the bundled tools
+  # to avoid re-fetching the same page or re-issuing the same web-search
+  # query within a TTL window: {Tool::WebScrape.visit} caches the rendered
+  # Markdown for a URL, and {Tool::Search::Engines.search} caches the
+  # rendered result list for a query (the query string itself acts as the
+  # key — keys are SHA-256 hashed, so any opaque string works).
+  #
+  # Each tool wires its own {UrlCache} instance against a dedicated
+  # subdirectory under {ROOT_DIR}, so a +web_search+ query string and a
+  # +web_scrape+ URL string can never collide on the same cache file. There
+  # is no global default singleton — pass a fresh instance to whichever
+  # code needs caching, or use {NULL} to disable caching entirely.
+  #
+  # One file per entry, named +<sha256>.txt+ under {#initialize}'s +dir+.
+  # Freshness is tracked via the file's mtime; there is no sidecar metadata.
+  # Stale entries are simply overwritten the next time {#fetch} is called
+  # with the same key. To clear the cache, +rm -rf+ the directory.
+  #
+  # Not thread-safe: if two callers race on the same cold key, both compute
+  # and both write the same file. That is the intended tradeoff to keep this
+  # under a few dozen lines — the worst-case cost is a duplicate fetch.
+  class UrlCache
+    # Root directory under which per-tool cache subdirectories live.
+    # Follows the XDG Base Directory spec: +$XDG_CACHE_HOME/pikuri/url_cache+
+    # if the env var is set to a non-empty value, else
+    # +~/.cache/pikuri/url_cache+. Each tool picks its own subdir
+    # (e.g. +"#{ROOT_DIR}/web_scrape"+) so keys from different tools cannot
+    # collide. The directory is created lazily on first cache write; pikuri
+    # does not pre-create it.
+    # @return [String]
+    ROOT_DIR = begin
+      xdg = ENV['XDG_CACHE_HOME']
+      cache_home = xdg && !xdg.empty? ? xdg : File.join(Dir.home, '.cache')
+      File.join(cache_home, 'pikuri', 'url_cache')
+    end.freeze
+
+    # Default freshness window: 2 hours, in seconds.
+    #
+    # Long enough to cover a single interactive session — revisiting
+    # a scraped page or re-running a similar search within the same
+    # working window hits the cache. Short enough that resuming the
+    # next day doesn't serve stale news, docs, or search results.
+    # Reference points: opencode keeps no cache, the +pi-web-fetch+
+    # community extension uses 15 minutes, +pi-web-search+ uses 5;
+    # 2 hours sits comfortably above the "single follow-up" window
+    # those numbers are aimed at without holding content across days.
+    # @return [Integer]
+    DEFAULT_TTL = 2 * 60 * 60
+
+    # @param ttl [Integer] freshness window in seconds; entries with an
+    #   mtime older than this are treated as misses
+    # @param dir [String] directory under which cache files live; created
+    #   lazily on first write
+    def initialize(ttl:, dir:)
+      @ttl = ttl
+      @dir = dir
+    end
+
+    # Return the cached payload for +url+ if a fresh entry exists, otherwise
+    # yield to compute it, persist the result, and return it.
+    #
+    # The block is only invoked on a miss. If the block raises, no file is
+    # written — errors are not cached.
+    #
+    # @param url [String] cache key; a URL or any opaque string identifier
+    # @yieldreturn [String] payload to store and return on a miss
+    # @return [String] cached or freshly-computed payload
+    def fetch(url)
+      path = path_for(url)
+      return File.read(path) if fresh?(path)
+
+      content = yield
+      FileUtils.mkdir_p(@dir)
+      File.write(path, content)
+      content
+    end
+
+    # @param path [String]
+    # @return [Boolean] true when +path+ exists and was written within the
+    #   TTL window
+    def fresh?(path)
+      File.exist?(path) && Time.now - File.mtime(path) < @ttl
+    end
+
+    # @param url [String]
+    # @return [String] absolute path of the cache file for +url+
+    def path_for(url)
+      File.join(@dir, "#{Digest::SHA256.hexdigest(url)}.txt")
+    end
+
+    # Null cache: a drop-in replacement that always misses and never
+    # persists. Use this in tests (or anywhere else you want caching off)
+    # without giving up the {UrlCache#fetch} contract.
+    NULL = Object.new
+    def NULL.fetch(_key)
+      yield
+    end
+    NULL.freeze
+  end
+end

data/lib/pikuri/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pikuri
+  # Gem version, advertised in +pikuri.gemspec+. Bump on every release
+  # following semver: patch for bug fixes, minor for backward-compatible
+  # 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.1'
+end