pikuri-core 0.0.3 → 0.0.4

data/lib/pikuri/agent.rb

@@ -48,8 +48,8 @@ module Pikuri
   # and gets a fresh +step_limit+ at +max: 1+ (defensive — the
   # synth has no tools and shouldn't trip it). The synth's
   # answer becomes the value reported by
-  # {#last_assistant_content}, so callers (notably
-  # {Tool::SubAgent}) still get a usable reply.
+  # {#last_assistant_content}, so callers (notably the +agent+ tool
+  # from +pikuri-subagents+) still get a usable reply.
   #
   # == Cancellation rescue
   #
@@ -332,14 +332,16 @@ module Pikuri
     #   set. Typically derived by +bin/pikuri-chat+ from its
     #   configured +openai_api_base+; leave +nil+ when the
     #   configured server is anything other than llama.cpp.
-    # @param name [String] identifier for this agent. Empty for
-    #   the main agent; sub-agents get monotonic hierarchical
-    #   names like +"sub_agent 0"+, +"sub_agent 1"+,
-    #   +"sub_agent 0_0"+, ... generated by {Tool::SubAgent} from
-    #   the parent's name + a per-parent counter. Forwarded to
-    #   listeners through {ListenerList#for_sub_agent} so name-
-    #   aware ones (notably {Listener::TokenLog}) can tag their
-    #   output.
+    # @param id [String] unique identifier for this agent. Empty
+    #   for the main agent; sub-agents get persona-rooted ids
+    #   like +"researcher 0"+, +"researcher 1"+, +"file_miner 0"+, ...
+    #   generated by the +agent+ tool from +pikuri-subagents+ from
+    #   the persona name + a per-persona counter. Forwarded to
+    #   listeners through {ListenerList#for_sub_agent} so id-aware
+    #   ones (notably {Listener::TokenLog}) can tag their output.
+    #   The word "id" is deliberate — "name" is reserved throughout
+    #   the codebase for the persona-name load (the value the LLM
+    #   picks in the +agent+ tool's +name:+ argument).
     # @param streaming [Boolean] opt into chunk-level streaming.
     #   When +true+, {#run_loop} passes the block returned by
     #   {.streaming_block} to +Chat#ask+, and ruby_llm requests
@@ -348,25 +350,24 @@ module Pikuri
     #   the listener stream as they arrive. When +false+ (the
     #   default), +Chat#ask+ runs in single-shot mode and only
     #   the message-level {Event::Thinking} / {Event::Assistant}
-    #   bookends fire from +after_message+. Read by
-    #   {Tool::SubAgent} so spawned sub-agents inherit the same
-    #   mode without an extra kwarg.
+    #   bookends fire from +after_message+. Read by the +agent+
+    #   tool from +pikuri-subagents+ so spawned sub-agents inherit
+    #   the same mode without an extra kwarg.
     # @yield [Configurator] yields a {Configurator} that collects
     #   tools (via {Configurator#add_tool} / {Configurator#add_tools}),
     #   listeners (via {Configurator#add_listener} /
     #   {Configurator#add_listeners}), system-prompt snippets (via
     #   {Configurator#append_system_prompt}), extension instances
     #   (via {Configurator#add_extension} — which fires +configure+
-    #   immediately), close handlers (via {Configurator#on_close}),
-    #   and an optional +sub_agent+ tool (via
-    #   {Configurator#allow_sub_agent}). The Configurator is the
-    #   *only* path for adding any of these — there are no parallel
-    #   ctor kwargs. The block is optional; an agent constructed
-    #   without one has no tools, no listeners, no extensions.
+    #   immediately), and close handlers (via
+    #   {Configurator#on_close}). The Configurator is the *only*
+    #   path for adding any of these — there are no parallel ctor
+    #   kwargs. The block is optional; an agent constructed without
+    #   one has no tools, no listeners, no extensions.
     # @return [Agent]
     def initialize(transport:, system_prompt:,
                    step_limit: nil, cancellable: nil, interloper: nil,
-                   context_window: nil, llama_probe_url: nil, name: '',
+                   context_window: nil, llama_probe_url: nil, id: '',
                    streaming: false,
                    &block)
       @transport = transport.model ? transport : transport.with(model: RubyLLM.config.default_model)
@@ -376,21 +377,19 @@ module Pikuri
       @system_prompt = system_prompt
       @step_limit = step_limit
       @interloper = interloper
-      @name = name
+      @id = id
       @streaming = streaming
       @synth_answer = nil
       @on_close_handlers = []
 
       # Single Configurator funnel for everything the block adds —
-      # tools, listeners, system-prompt snippets, extensions
-      # (both newly-configured via #add_extension and inherited
-      # via #inherit_extensions for sub-agents), on_close handlers,
-      # and the sub-agent request. See IDEAS.md §"Extension protocol
-      # design".
+      # tools, listeners, system-prompt snippets, extensions, and
+      # on_close handlers. See {Configurator} for the per-method
+      # contract.
       configurator = Configurator.new(
         transport: @transport,
         system_prompt_base: system_prompt,
-        name: @name,
+        id: @id,
         streaming: @streaming,
         step_limit: @step_limit,
         cancellable: @cancellable,
@@ -400,6 +399,7 @@ module Pikuri
       block&.call(configurator)
 
       @tools = configurator.tools.dup
+      @sub_agent_tools = configurator.sub_agent_tools.dup
       @listeners = ListenerList.new(configurator.listeners)
       configurator.system_prompt_additions.each do |snippet|
         @system_prompt = "#{@system_prompt}\n\n#{snippet}"
@@ -430,25 +430,6 @@ module Pikuri
       # before any Tokens event arrives.
       @listeners.emit(Event::ContextCap.new(cap: @context_window_cap))
 
-      # Sub-agent tool: constructed *after* @tools is final and
-      # @context_window_cap is set, so its snapshot of the parent's
-      # tool list doesn't include itself (recursion guard) and the
-      # cap can be threaded through to spawned sub-agents. The new
-      # +Tool::SubAgent+ instance is appended to both +@tools+ and
-      # +@chat+, so sub-agents inheriting via the snapshot still
-      # get the surrounding tool set but never the +sub_agent+ tool
-      # itself. See {Configurator#allow_sub_agent}.
-      if configurator.sub_agent_request
-        if @tools.any?(Tool::SubAgent)
-          raise 'Tool::SubAgent must not be added via c.add_tool when c.allow_sub_agent ' \
-                'is used; Agent auto-registers it from the Configurator request.'
-        end
-
-        sub_tool = Tool::SubAgent.new(self, max_steps: configurator.sub_agent_request.max_steps)
-        @tools << sub_tool
-        @chat.with_tool(sub_tool.to_ruby_llm_tool)
-      end
-
       # Bind sweep — each extension gets its chance to install
       # per-agent state (dynamic tools via #internal_add_tool,
       # per-agent close hooks via #on_close, etc.) now that the
@@ -474,19 +455,30 @@ module Pikuri
     #   agent was constructed with — same model id / provider /
     #   assume-model-exists flag passed to every +RubyLLM.chat+
     #   call originating from this agent (the main chat, the
-    #   synthesizer rescue, the sub-agent tool). Read by
-    #   {Tool::SubAgent} so spawned sub-agents reuse the same
-    #   transport.
+    #   synthesizer rescue, the +agent+ tool from
+    #   +pikuri-subagents+). Read by extensions that need to spawn
+    #   their own ruby_llm calls (e.g. MCP description synthesis,
+    #   sub-agent delegation).
     attr_reader :transport
 
     # @return [Array<Tool>] this agent's tool list in declaration
-    #   order. Snapshotted by {Tool::SubAgent} so spawned
-    #   sub-agents inherit the parent's tools (minus the
-    #   sub-agent tool itself, which {#allow_sub_agent} appends
-    #   to +@tools+ only after the snapshot has been taken —
-    #   recursion guard).
+    #   order. Read by extensions that filter against it (notably
+    #   the +agent+ tool from +pikuri-subagents+, which picks the
+    #   sub-agent's toolset from the parent's instances so any
+    #   already-bound workspace/confirmer wiring travels along).
+    #   Tools listed here are also the ones registered with
+    #   ruby_llm — the parent LLM can call any of them. Compare
+    #   with {#sub_agent_tools}.
     attr_reader :tools
 
+    # @return [Array<Tool>] tools registered via
+    #   {Configurator#add_sub_agent_tool}, in declaration order.
+    #   Invisible to the parent LLM (never sent to ruby_llm);
+    #   available only to sub-agents whose persona +tool_names+
+    #   match. See {Configurator}'s "Two tool pools" header for
+    #   the trifecta-defense rationale.
+    attr_reader :sub_agent_tools
+
     # @return [String] resolved model id from {#transport}.
     #   Convenience delegator for callers that don't need the
     #   full transport bundle.
@@ -496,12 +488,10 @@ module Pikuri
 
     # @return [String] system prompt actually sent to the chat —
     #   equal to the constructor's +system_prompt:+ argument plus
-    #   any snippets appended by extensions during
-    #   {Configurator#append_system_prompt} (Skills'
-    #   +<available_skills>+, MCP's +<available_mcps>+, ...).
-    #   {Tool::SubAgent} forwards this already-augmented value to
-    #   spawned sub-agents so they see the same advertisements
-    #   without re-running extension configure.
+    #   any snippets appended via {Configurator#append_system_prompt}
+    #   (extensions' +<available_skills>+ / +<available_mcps>+ /
+    #   +<available_agents>+, ...). Not inherited by sub-agents —
+    #   each persona owns its own system prompt verbatim.
     attr_reader :system_prompt
 
     # @return [ListenerList] the listener list attached to this
@@ -510,54 +500,55 @@ module Pikuri
 
     # @return [Control::StepLimit, nil] the step-budget control
     #   this agent was constructed with, or +nil+ when none.
-    #   Read by {Tool::SubAgent} so spawned sub-agents derive
-    #   their own.
     attr_reader :step_limit
 
     # @return [Control::Cancellable, nil] the cancellation
     #   control this agent was constructed with, or +nil+ when
-    #   none. Read by {Tool::SubAgent} so spawned sub-agents
-    #   share the same instance.
+    #   none. Read by extensions that propagate cancellation to
+    #   their own LLM calls (e.g. the +agent+ tool from
+    #   +pikuri-subagents+ shares it with spawned sub-agents so
+    #   one Ctrl+C stops the tree).
     attr_reader :cancellable
 
     # @return [Control::Interloper, nil] the mid-loop user-input
     #   control this agent was constructed with, or +nil+ when
-    #   none. Not propagated to sub-agents — see
-    #   {Control::Interloper#for_sub_agent}.
+    #   none.
     attr_reader :interloper
 
-    # @return [String] this agent's identifier — empty for the
-    #   main agent; for sub-agents, the hierarchical id assigned
-    #   by {Tool::SubAgent} (e.g. +"sub_agent 0"+,
-    #   +"sub_agent 1"+, +"sub_agent 0_0"+). Read by the
-    #   sub-agent tool so spawned sub-agents prefix their own
-    #   names with this one, and propagated to listeners via
-    #   {ListenerList#for_sub_agent} so name-aware ones can tag
-    #   output.
-    attr_reader :name
+    # @return [String] this agent's unique identifier — empty for
+    #   the main agent; for sub-agents, the persona-rooted id
+    #   assigned by the +agent+ tool from +pikuri-subagents+ (e.g.
+    #   +"researcher 0"+, +"researcher 1"+, +"file_miner 0"+).
+    #   Propagated to listeners via {ListenerList#for_sub_agent(id:)}
+    #   so id-aware ones can tag output. Distinct from the persona's
+    #   +name+ (the value the LLM picks in the +agent+ tool's
+    #   +name:+ argument).
+    attr_reader :id
 
     # @return [Boolean] +true+ when this agent opted into
     #   chunk-level streaming (see the +streaming:+ kwarg on
-    #   {#initialize}); +false+ otherwise. Read by
-    #   {Tool::SubAgent} so spawned sub-agents inherit the same
-    #   mode.
+    #   {#initialize}); +false+ otherwise. Read by extensions that
+    #   spawn their own ruby_llm calls (notably the +agent+ tool
+    #   from +pikuri-subagents+, so spawned sub-agents inherit the
+    #   same mode).
     attr_reader :streaming
 
     # @return [Array<Extension>] extension instances bound to this
-    #   agent — added via {Configurator#add_extension} (new — runs
-    #   +configure+ now and binds later) or {Configurator#inherit_extensions}
-    #   (sub-agent inheritance — skips +configure+, just binds), both
-    #   inside the +Agent.new+ block. Read by {Tool::SubAgent} so
-    #   spawned sub-agents inherit the parent's extension list and
-    #   re-bind them via the bind sweep.
+    #   agent — added via {Configurator#add_extension} inside the
+    #   +Agent.new+ block. Each instance's +configure+ runs during
+    #   the block and its +bind+ runs at the end of
+    #   {#initialize}, once per registration (so once per parent
+    #   agent in the typical setup; sub-agents do not inherit
+    #   extensions).
     attr_reader :extensions
 
     # @return [Integer, nil] context-window cap resolved by
     #   {ContextWindowDetector} at construction time. +nil+ when
     #   no source produced a value (custom local model with no
     #   override and no reachable llama.cpp +/props+). Read by
-    #   {Tool::SubAgent} so spawned sub-agents inherit the same
-    #   cap without re-probing.
+    #   extensions that spawn their own ruby_llm calls (notably
+    #   the +agent+ tool from +pikuri-subagents+, so spawned
+    #   sub-agents inherit the same cap without re-probing).
     attr_reader :context_window_cap
 
     # Final assistant message content for the most recent
@@ -629,14 +620,14 @@ module Pikuri
 
       # Synth runs under this agent's identity but on a fresh
       # chat with a different system prompt, so it gets a
-      # distinct +_synthesizer+ suffix on the name — same +_+
+      # distinct +_synthesizer+ suffix on the id — same +_+
       # separator the sub-agent generator uses, so main becomes
-      # +"synthesizer"+ and a sub-agent +"sub_agent 0"+ becomes
-      # +"sub_agent 0_synthesizer"+. Any +TokenLog+ in the list
+      # +"synthesizer"+ and a sub-agent +"researcher 0"+ becomes
+      # +"researcher 0_synthesizer"+. Any +TokenLog+ in the list
       # tags the synth's prompt under that bracket so it's
       # obvious from the log which turns were the rescue rather
       # than the original loop.
-      synth_name = @name.empty? ? 'synthesizer' : "#{@name}_synthesizer"
+      synth_id = @id.empty? ? 'synthesizer' : "#{@id}_synthesizer"
       synth_chat = RubyLLM.chat(**@transport.to_h)
       # Defensive step limit on the synth: the synth has no
       # tools so it should never trip +before_tool_call+, but
@@ -647,7 +638,7 @@ module Pikuri
         chat: synth_chat,
         parent_messages: @chat.messages,
         user_message: user_message,
-        listeners: @listeners.for_sub_agent(name: synth_name),
+        listeners: @listeners.for_sub_agent(id: synth_id),
         step_limit: synth_step_limit,
         cancellable: @cancellable,
         streaming: @streaming
@@ -706,9 +697,10 @@ module Pikuri
     # +Pikuri::Tool+ entirely."
     #
     # The added tool does NOT enter +@tools+, only +@chat+'s tool
-    # list. {Tool::SubAgent} therefore cannot snapshot it (which is
-    # the whole point — activation is strictly per-agent, see
-    # IDEAS.md §"Per-agent activation, no propagation").
+    # list. Sub-agents (the +agent+ tool from +pikuri-subagents+)
+    # therefore cannot snapshot it — which is the whole point:
+    # activation is strictly per-agent, see IDEAS.md §"Per-agent
+    # activation, no propagation".
     #
     # @param ruby_llm_tool [Class] subclass of +RubyLLM::Tool+
     # @return [void]
@@ -721,11 +713,11 @@ module Pikuri
     #
     # @example
     #   agent.to_s
-    #   # => "Agent(model=qwen3-35b, tools=4, listeners=[Terminal])"
+    #   # => "Agent(id=, model=qwen3-35b, tools=4, listeners=[Terminal])"
     #
     # @return [String]
     def to_s
-      "Agent(model=#{model}, tools=#{@tools.size}, listeners=#{@listeners})"
+      "Agent(id=#{@id}, model=#{model}, tools=#{@tools.size}, listeners=#{@listeners})"
     end
   end
 end

data/lib/pikuri/file_type.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'pdf-reader'
+
+module Pikuri
+  # Magic-byte content sniffing + text extraction, centralised. Three
+  # responsibilities:
+  #
+  # * {.detect_mime} — recognise a file from its leading bytes. Returns
+  #   a MIME String for formats pikuri knows how to handle specially
+  #   ({+application/pdf+}, the four image formats), or +nil+ for
+  #   "unrecognised — could be text, could be opaque binary; caller
+  #   decides".
+  # * {.binary?} — heuristic text-vs-binary classifier. Independent of
+  #   {.detect_mime}: a file can be both recognised (e.g. PDF) *and*
+  #   binary. {.detect_mime} tells you what the bytes are;
+  #   {.binary?} tells you whether they're safe to render as text.
+  # * {.read_as_text} — read a file and return its content as plain
+  #   UTF-8 text. PDFs go through +pdf-reader+ page-by-page; plain
+  #   text passes through; images / binaries / missing files raise.
+  #   The pure-extraction shape consumers like +Pikuri::VectorDb+'s
+  #   indexer want (no LLM-tool concerns — no paging, no line
+  #   numbering, no byte caps; just bytes-in-text-out).
+  #
+  # {.detect_mime} and {.binary?} accept either a +String+ of bytes
+  # (sample taken by the caller) or a +Pathname+ — when given a path,
+  # the module opens the file in binary mode and reads {SAMPLE_BYTES}
+  # for the sniff itself. The Pathname form is the convenience path;
+  # the bytes form is for callers that already have the sample or are
+  # calling both methods on the same file and want to avoid a second
+  # open. {.read_as_text} takes a +Pathname+ only — there's no
+  # bytes-in shortcut because the PDF case needs to seek the file.
+  #
+  # == Why a separate module
+  #
+  # Without this module, magic-byte tables and the binary heuristic
+  # ended up scattered through whichever tool needed them — first PDF
+  # in {Workspace::Read}, then images alongside it, then a copy of
+  # {.binary?} reached for by {Workspace::Edit}. Collecting the
+  # detection logic here lets {Read} focus on routing
+  # (mime-to-formatter), {Edit} drop its cross-tool reach, and new
+  # tools (a future +Workspace::Diff+, an attachment-aware web fetcher,
+  # ...) share one set of magic-byte truths.
+  #
+  # == Deliberate non-goals
+  #
+  # * *Not a full MIME database.* The set grows when a pikuri tool
+  #   needs a new format, not speculatively. Keeps the "audit in an
+  #   evening" ceiling honest.
+  # * *No path / extension fallback.* Extensions lie (a renamed
+  #   +.png+ → opaque garbage); magic-byte detection on the actual
+  #   content is the source of truth. Callers that need
+  #   extension-based behaviour can layer it themselves.
+  # * *No convenience predicates* like +image?+ / +pdf?+. Callers do
+  #   +mime == 'application/pdf'+ or +mime&.start_with?('image/')+ —
+  #   one extra character, zero added API surface.
+  module FileType
+    module_function
+
+    # @return [Integer] recommended number of bytes to sample for
+    #   {.detect_mime} and {.binary?}. Big enough to catch every
+    #   prefix pikuri sniffs today (the largest is WebP's 12-byte
+    #   container header) with comfortable slack; small enough that
+    #   reading it off any reasonable filesystem is effectively free.
+    SAMPLE_BYTES = 4096
+
+    # @return [Float] fraction of the sample that may be non-printable
+    #   before {.binary?} flags the bytes as binary. Matches opencode's
+    #   threshold.
+    BINARY_NONPRINTABLE_THRESHOLD = 0.30
+
+    # @return [Hash{String => String}] magic-byte prefixes → MIME types
+    #   for the image formats with flat (offset-zero, fixed-length)
+    #   signatures. WebP isn't here — its signature is split across the
+    #   RIFF container header — and is handled directly in
+    #   {.detect_mime}.
+    IMAGE_MAGIC_BYTES = {
+      "\x89PNG\r\n\x1a\n".b => 'image/png',
+      "\xff\xd8\xff".b      => 'image/jpeg',
+      "GIF87a".b            => 'image/gif',
+      "GIF89a".b            => 'image/gif'
+    }.freeze
+
+    # @return [String] PDF magic prefix. Every conformant PDF starts
+    #   with this five-byte ASCII sequence per ISO 32000-1 §7.5.2.
+    PDF_MAGIC = '%PDF-'
+
+    # Recognise a file from its leading bytes. Returns the MIME type
+    # as a String for formats pikuri handles specially, or +nil+ for
+    # "unrecognised" — callers interpret +nil+ themselves (text,
+    # opaque binary, ...).
+    #
+    # @param input [String, Pathname] the bytes to inspect, or a
+    #   +Pathname+ that this method opens in binary mode and reads up
+    #   to {SAMPLE_BYTES} from. Caller is responsible for verifying the
+    #   path exists; missing-file errors propagate as +Errno::ENOENT+.
+    # @return [String, nil]
+    def detect_mime(input)
+      bytes = sample_of(input)
+      return 'application/pdf' if bytes.start_with?(PDF_MAGIC)
+
+      IMAGE_MAGIC_BYTES.each do |prefix, mime|
+        return mime if bytes.start_with?(prefix)
+      end
+      return 'image/webp' if bytes.bytesize >= 12 &&
+                             bytes.byteslice(0, 4) == 'RIFF'.b &&
+                             bytes.byteslice(8, 4) == 'WEBP'.b
+
+      nil
+    end
+
+    # Heuristic text-vs-binary classifier matching opencode's: any
+    # +NUL+ byte forces +true+; otherwise count bytes outside the
+    # printable +\t \n \v \f \r+ + ASCII-32..126 range and ratio
+    # against the sample size. UTF-8 continuation bytes (0x80-0xBF)
+    # are >127 so they sit outside the non-printable ranges and pass
+    # through unflagged, letting UTF-8 text read fine. An empty
+    # sample is treated as not-binary (callers reading an empty file
+    # take the empty-text path).
+    #
+    # @param input [String, Pathname] the bytes to inspect, or a
+    #   +Pathname+ that this method opens in binary mode and reads up
+    #   to {SAMPLE_BYTES} from. Caller is responsible for verifying
+    #   the path exists.
+    # @return [Boolean]
+    def binary?(input)
+      bytes = sample_of(input)
+      return false if bytes.empty?
+
+      non_printable = 0
+      bytes.each_byte do |b|
+        return true if b.zero?
+
+        non_printable += 1 if b < 9 || (b > 13 && b < 32)
+      end
+      non_printable.to_f / bytes.bytesize > BINARY_NONPRINTABLE_THRESHOLD
+    end
+
+    # Read +path+ and return its content as plain UTF-8 text. Two
+    # extraction paths, picked by {.detect_mime}:
+    #
+    # * **PDF** — walked page-by-page via +pdf-reader+; each page's
+    #   extracted text is stripped and pages are joined with a blank
+    #   line. A scanned-image PDF (no extractable text) comes back as
+    #   the empty String — a deliberate silent skip, callers detect by
+    #   length if they care.
+    # * **Plain text** — anything that {.detect_mime} doesn't
+    #   recognise and that {.binary?} accepts. Read with UTF-8
+    #   encoding; behaviour on non-UTF-8 bytes is whatever +File.read+
+    #   does with +encoding: Encoding::UTF_8+ (which is "leave invalid
+    #   bytes in, let downstream decide").
+    #
+    # Refusal cases — all raise rather than returning a sentinel
+    # because the callers are internal pikuri code, not an LLM
+    # tool. The LLM-facing +Workspace::Read+ does its own routing and
+    # returns "Error: ..." observations; that's a separate concern.
+    #
+    # * Path doesn't exist → +Errno::ENOENT+.
+    # * Path is a directory → +ArgumentError+.
+    # * Image (PNG / JPEG / GIF / WebP per {.detect_mime}) →
+    #   +ArgumentError+; images aren't text.
+    # * Binary content (per {.binary?}) and not a recognised MIME →
+    #   +ArgumentError+.
+    # * Malformed PDF — +pdf-reader+'s
+    #   +MalformedPDFError+ / +UnsupportedFeatureError+ /
+    #   +InvalidPageError+ are re-raised as a +RuntimeError+ with the
+    #   path included so callers don't need to know pdf-reader's
+    #   exception hierarchy.
+    #
+    # @param path [Pathname] file to read.
+    # @return [String] UTF-8 text. May be empty (empty text file, or
+    #   scanned-image PDF).
+    # @raise [ArgumentError] if +path+ isn't a +Pathname+, points at
+    #   a directory, is an image, or is binary.
+    # @raise [Errno::ENOENT] if +path+ doesn't exist.
+    # @raise [RuntimeError] on a malformed / unsupported PDF.
+    def read_as_text(path)
+      raise ArgumentError, "expected Pathname, got #{path.class}" unless path.is_a?(Pathname)
+      raise Errno::ENOENT, path.to_s unless path.exist?
+      raise ArgumentError, "#{path} is a directory" if path.directory?
+
+      mime = detect_mime(path)
+      return read_pdf_text(path) if mime == 'application/pdf'
+      raise ArgumentError, "#{path} is an image (#{mime}); cannot extract as text" if mime&.start_with?('image/')
+      raise ArgumentError, "#{path} appears to be binary; cannot extract as text" if binary?(path)
+
+      path.read(encoding: Encoding::UTF_8)
+    end
+
+    # Walk a PDF page-by-page via +pdf-reader+, returning a single
+    # String with non-empty page texts joined by blank lines. Catches
+    # the three +PDF::Reader+ exceptions Workspace::Read also handles
+    # and re-raises them as +RuntimeError+ with the path included.
+    #
+    # @param path [Pathname]
+    # @return [String]
+    # @raise [RuntimeError] on malformed / unsupported PDF.
+    def read_pdf_text(path)
+      pages = path.open('rb') do |io|
+        ::PDF::Reader.new(io).pages.map { |p| p.text.strip }
+      end
+      pages.reject(&:empty?).join("\n\n")
+    rescue ::PDF::Reader::MalformedPDFError,
+           ::PDF::Reader::UnsupportedFeatureError,
+           ::PDF::Reader::InvalidPageError => e
+      raise "Cannot extract PDF text from #{path}: " \
+            "#{e.class.name.split('::').last}: #{e.message}"
+    end
+    private_class_method :read_pdf_text
+
+    # Coerce an +input+ argument into a bytes String for the sniffs.
+    # +String+ inputs are returned as-is (caller already sampled);
+    # +Pathname+ inputs are opened in binary mode and up to
+    # {SAMPLE_BYTES} are read off the front. Empty files come back
+    # as an empty String — {.binary?} treats that as not-binary and
+    # {.detect_mime} returns +nil+ for it, which is what the
+    # empty-text path wants.
+    #
+    # @param input [String, Pathname]
+    # @return [String] raw bytes (ASCII-8BIT encoding for the path
+    #   case; whatever the caller passed for the bytes case)
+    # @raise [ArgumentError] if +input+ is neither a +String+ nor a
+    #   +Pathname+ — refuses to guess, since a bare String could be
+    #   either a path or actual bytes.
+    def sample_of(input)
+      case input
+      when String
+        input
+      when Pathname
+        input.open('rb') { |io| io.read(SAMPLE_BYTES) || +'' }
+      else
+        raise ArgumentError, "expected String bytes or Pathname, got #{input.class}"
+      end
+    end
+    private_class_method :sample_of
+  end
+end

data/lib/pikuri/subprocess.rb

@@ -72,10 +72,17 @@ module Pikuri
     #   interpretation is wanted; +argv+ is passed to +exec+
     #   directly, so no implicit shell expansion happens here.
     # @param chdir [String, Pathname] working directory
+    # @param env [Hash{String=>String}] extra environment variables to
+    #   set in the child process. The child otherwise inherits the
+    #   parent's full environment; entries in +env+ override or add to
+    #   it. Default +{}+ (pure inheritance). Used by {Code::Bash} to
+    #   thread {Pikuri::Workspace::Filesystem#env} (host git identity,
+    #   etc.) into a bash subprocess whose sandbox would otherwise
+    #   strip the host's config files.
     # @return [Subprocess] handle — call {#wait} to block for the
     #   direct child to exit and read the captured output
-    def self.spawn(*argv, chdir:)
-      stdin, io, wait_thr = Open3.popen2e(*argv, chdir: chdir.to_s, pgroup: true)
+    def self.spawn(*argv, chdir:, env: {})
+      stdin, io, wait_thr = Open3.popen2e(env, *argv, chdir: chdir.to_s, pgroup: true)
       stdin.close
       register(wait_thr.pid)
       new(io: io, wait_thr: wait_thr)