pikuri-os 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b962310fa6c20cae48446f97272e6e9865c22d3700128366e4f7082a23ea501
+  data.tar.gz: e0d0b77825dbc716dc3cbb113867a72e4a56395877a00e9763936aeb1709ee2b
+SHA512:
+  metadata.gz: 55f1d13f4f9000286e4f0556cf7e29b33ee24135f3d222c2963eadbf6d73d472cacfcbd893d3d16c27e44c84416effc66c823d54f7513b3f635b2bed10cbfdec
+  data.tar.gz: 3595db2fd68deb8e89767554e6b08945be88dcd17fbd29d288b1c954606825b92619c36edc87dc76d15f7ac5b73ce36ae2fb1bdc2aa4579d7b0152671a26e5ba

data/README.md

@@ -0,0 +1,53 @@
+# pikuri-os
+
+Offline Linux/OS helper agent + OS-integration tools for the
+[pikuri](https://codeberg.org/mvysny/pikuri) AI-assistant toolkit.
+
+`pikuri-os` is the home of `bin/pikuri-os`: a single, local,
+**network-severed** agent that understands and operates the host OS —
+answer questions about the machine, find and open files, read logs and
+explain errors, advise on configuration. It is the federation's
+privacy-first `@os` member shipped as a standalone single agent (walked
+through in [the guide's OS-assistant chapter](../book/os-assistant.md); see
+[`ideas/pikuri-os.md`](../ideas/pikuri-os.md) for the design
+origin and the work still deferred).
+
+Posture (the load-bearing parts):
+
+- **Egress severed at the kernel.** Bash runs in a full-filesystem,
+  net-isolated sandbox (the inverse of the coding agent's networked
+  one), so the trifecta's exfiltration leg is gone by construction —
+  not by a prompt.
+- **Every mutation confirmed.** `Bash`/`Write`/`Edit` route through the
+  confirmer; a conservative deterministic auto-confirmer waves through
+  only provably-read-only commands.
+- **Advise, don't execute, anything privileged or networked.** Anything
+  needing `sudo` or the network is handed to the user to run.
+- **Memory is a single `MACHINE.md`**, not mem0 — a `CLAUDE.md` for this
+  host, appended to the system prompt at boot and editable through the
+  confirmed write path.
+
+**Opt-in web research.** `--with-internet` enables web access, but
+quarantined: `web_search` / `web_scrape` / `fetch` live inside an isolated
+`RESEARCHER` sub-agent that has the web tools but **no filesystem** —
+reached via the `agent` tool. The main agent holds **no direct web
+tool**, so it has zero unconfirmed egress; you approve each research task
+before it runs (the human, not the model, authors what leaves the
+machine), and the researcher — having no private data — can at worst leak
+that approved task plus the public pages it read. This is a *separate*
+network boundary from the bash sandbox, which **stays kernel-severed
+regardless**. Off by default; the agent stays networkless until you pass
+the flag. See [`ideas/more-confirmers.md`](../ideas/more-confirmers.md)
+for the harder pieces still deferred (editable task prompts, a
+reject-reason channel).
+
+**Target platform:** Ubuntu 26.04 LTS or newer, GNOME desktop.
+
+Depends on `pikuri-core` (Agent + Tool framework), `pikuri-workspace`
+(file tools + confirmer), and `pikuri-code` (Bash + sandbox).
+Deliberately **not** `pikuri-mcp` / `pikuri-memory` / `pikuri-vectordb`
+— severing those keeps the no-egress, audit-first posture honest.
+
+> Status: skeleton. The OS-specific surface (localsearch-backed
+> content search, `MACHINE.md` memory, boot grounding) and the binary
+> land incrementally.

data/lib/pikuri/os/extension.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Os
+    # One-call wiring for the offline OS-helper agent. Adding this single
+    # extension to an +Agent.new+ block gives the complete surface — the
+    # five workspace file tools, +bash+ (net-severable, with the
+    # passive-command detector), the file-index tools, and the machine grounding +
+    # +MACHINE.md+ memory folded into the system prompt.
+    #
+    # A composite: +configure+ adds {Pikuri::Workspace::Extension} and
+    # {Pikuri::Code::Extension} as sub-extensions, then layers on the
+    # OS-specific tools and prompt sections.
+    #
+    # == Confirmation policy
+    #
+    # The caller passes the *human* confirmer. The file tools get it via
+    # {Pikuri::Workspace::Extension} with +confirm_all_writes: true+: since
+    # this agent roams the full disk (no containment), *every* writable
+    # Write/Edit confirms with a diff and an unwritable target
+    # short-circuits to "ask the user to sudo" (see
+    # {Pikuri::Workspace::WriteGate}, book/os-assistant.md). +Bash+ gets the same
+    # confirmer plus a {Pikuri::Code::Bash::PassiveCommandDetector}, so
+    # provably passive commands skip the prompt and everything else
+    # reaches the human — bash mutations and file-tool writes both always
+    # confirm.
+    #
+    # The detector is built +allow_git: true+, so passive git verbs skip
+    # the prompt too (no per-repo trust prompt). Safe here *only because*
+    # {Pikuri::Code::Bash::GIT_HARDENING} neutralizes the hostile
+    # +core.fsmonitor+ vector that fires on a plain +git status+; the
+    # accepted residual is diff-driver execution on an attacker-written
+    # +.git/config+ (confined to non-clone-delivered repos). Full detail:
+    # {Pikuri::Code::Bash::PassiveCommandDetector}'s +allow_git:+ yardoc.
+    #
+    # == Sandbox
+    #
+    # The +sandbox+ is the caller's choice (default {Pikuri::Code::Bash::Sandbox::NONE}).
+    # The OS-helper binary passes {Pikuri::Code::Bash::Sandbox::FullFsNoNet}
+    # for the net-severed, full-filesystem posture; that decision (and its
+    # fail-loud probe) lives in the binary, so a differently-hosted client
+    # can isolate differently.
+    #
+    # == Degradation
+    #
+    # The file-index tools need a usable index backend. The extension wires
+    # them on the first of {FILE_INDEX_BACKENDS} that is
+    # {LocalSearch.available? usable} — {LocalSearch} (GNOME, zero-setup),
+    # then {Recoll} (DE-independent, but only with a built index). When none
+    # is usable it logs and omits the tools — the agent still constructs and
+    # works (bash + file tools).
+    class Extension
+      include Pikuri::Agent::Extension
+
+      LOGGER = Pikuri.logger_for('Os::Extension')
+
+      # @return [Array<Module>] file-index backends in preference order; the
+      #   first one whose +#available?+ is true backs the fileindex tools.
+      FILE_INDEX_BACKENDS = [LocalSearch, Recoll].freeze
+
+      # @param filesystem [Pikuri::Workspace::Filesystem] the host fs view
+      #   for the file tools and bash (typically
+      #   {Pikuri::Workspace::Filesystem::AllowAll} for full-host access).
+      # @param confirmer [Pikuri::Workspace::Confirmer] the *human*
+      #   confirmer; Bash is auto-gated on top of it (see "Confirmation
+      #   policy").
+      # @param sandbox [Pikuri::Code::Bash::Sandbox] bash subprocess
+      #   isolation; defaults to {Pikuri::Code::Bash::Sandbox::NONE}.
+      # @param read_only [Pikuri::Workspace::ReadOnly, nil] the shared
+      #   read-only flag; when present it is threaded into both
+      #   {Pikuri::Workspace::Extension} (gates Write/Edit) and
+      #   {Pikuri::Code::Extension} (wires plan mode), so one instance
+      #   drives the whole posture. +nil+ leaves plan mode unavailable.
+      # @param memory [MachineMemory] the MACHINE.md reader.
+      # @param system_info [SystemInfo] the boot-time machine facts.
+      # @param file_index_backends [Array<Module>] file-index backends in
+      #   preference order; defaults to {FILE_INDEX_BACKENDS}. The first
+      #   usable one backs the fileindex tools; if none is usable they are
+      #   omitted.
+      def initialize(filesystem:, confirmer:,
+                     sandbox: Pikuri::Code::Bash::Sandbox::NONE, read_only: nil,
+                     memory: MachineMemory.new, system_info: SystemInfo.new,
+                     file_index_backends: FILE_INDEX_BACKENDS)
+        @filesystem = filesystem
+        @confirmer = confirmer
+        @sandbox = sandbox
+        @read_only = read_only
+        @memory = memory
+        @system_info = system_info
+        @file_index_backends = file_index_backends
+      end
+
+      # @param c [Pikuri::Agent::Configurator]
+      # @return [void]
+      def configure(c)
+        c.add_extension(Pikuri::Workspace::Extension.new(
+                          filesystem: @filesystem, confirmer: @confirmer, read_only: @read_only,
+                          confirm_all_writes: true
+                        ))
+        c.add_extension(Pikuri::Code::Extension.new(
+                          filesystem: @filesystem,
+                          confirmer: @confirmer,
+                          passive_detector: Pikuri::Code::Bash::PassiveCommandDetector.new(allow_git: true),
+                          sandbox: @sandbox,
+                          read_only: @read_only
+                        ))
+
+        backend = @file_index_backends.find(&:available?)
+        if backend
+          c.add_tool FileindexSearch.new(backend: backend)
+          c.add_tool FileindexRead.new(backend: backend)
+        else
+          tried = @file_index_backends.map(&:label).join(' / ')
+          LOGGER.warn("no usable file index (tried #{tried}); fileindex_search / " \
+                      'fileindex_read disabled on this host.')
+        end
+
+        nil
+      end
+
+      # Two grounding sections: the machine facts and the MACHINE.md notes
+      # (or an affordance pointing at where to record them). System-info is
+      # memoized at its source (re-pull on clear is free); the memory
+      # section is read **fresh**, so MACHINE.md edits surface on a
+      # "/clear".
+      #
+      # @return [Array<String>]
+      def system_prompt_snippets
+        [@system_info.prompt_section, @memory.prompt_section || empty_memory_affordance]
+      end
+
+      private
+
+      # System-prompt line shown when MACHINE.md doesn't exist yet, so the
+      # agent still knows where to record durable facts.
+      #
+      # @return [String]
+      def empty_memory_affordance
+        <<~SECTION.chomp
+          # Notes about this machine
+
+          No durable notes recorded yet. You can record lasting facts about this
+          computer's setup by creating and editing #{@memory.path}.
+        SECTION
+      end
+    end
+  end
+end

data/lib/pikuri/os/fileindex_read.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Pikuri
+  module Os
+    # The +fileindex_read+ tool — read a file's full text *as stored in
+    # the desktop index*, line-paged like {Pikuri::Workspace::Read}. The
+    # companion to {FileindexSearch} (which locates + previews one match),
+    # sharing its swappable +backend:+ ({LocalSearch} / {Recoll}).
+    #
+    # It reads the index, not the file: the index already holds every
+    # indexed file's extracted plain text — PDFs/office docs included — so
+    # this returns them in full with no extractor dependency. The cost is
+    # that it's the *indexed snapshot* (can lag very recent edits, covers
+    # only files the index knows); for a live or system text file
+    # (+/etc+, +/var/log+, a just-written file), read it directly instead.
+    #
+    # +offset+ / +limit+ page exactly as in {Pikuri::Workspace::Read},
+    # windowed through {Pikuri::Extractor.extract_paged} (a +StringIO+ over
+    # the stored text) with the same +cat -n+ + trailer, caps, and markers.
+    #
+    # Sharing: +P_stateless+ — the backend is a stateless module over a
+    # read-only index, so one instance serves any number of agents.
+    class FileindexRead < Pikuri::Tool
+      # @return [Integer] default +limit+ (lines per call); the shared
+      #   page default, so it matches +read+.
+      DEFAULT_LIMIT = Pikuri::Extractor::PAGE_DEFAULT_LIMIT
+
+      # @return [String] human-readable byte cap for the trailer.
+      MAX_BYTES_LABEL = "#{Pikuri::Extractor::PAGE_MAX_BYTES / 1024} KB"
+
+      # @return [String] opencode-shape description (summary + Usage).
+      DESCRIPTION = <<~DESC
+        Read a file's full text from the desktop search index, with line numbers.
+
+        Usage:
+        - The companion to fileindex_search: after it locates a file, read the file in full here.
+        - Reads the indexed text, so PDFs and office documents come back as their extracted text — no special handling needed.
+        - This is the indexed snapshot: it can lag very recent edits, and only files the index knows are available. For a live or system text file (/etc, /var/log, a just-written file), use the read tool instead.
+        - Output is line-numbered `cat -n` style; use `offset` and `limit` to page. When the response ends in `Use offset=N to continue`, call again with that offset.
+      DESC
+
+      # @param backend [Module] a file-index backend ({LocalSearch} /
+      #   {Recoll}); only +#read_text+ and +#check_binaries!+ are used here.
+      # @raise [RuntimeError] if the backend's binary isn't on +PATH+.
+      # @return [FileindexRead]
+      def initialize(backend:)
+        @backend = backend
+        backend.check_binaries!
+        super(
+          name: 'fileindex_read',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :path,
+                              'Absolute path to the file (as returned by ' \
+                              'fileindex_search), e.g. "/home/u/Documents/report.pdf".'
+            p.optional_integer :offset,
+                               'Line number to start reading from (1-indexed). ' \
+                               'Defaults to 1, e.g. 200.'
+            p.optional_integer :limit,
+                               'Maximum number of lines to read. Defaults to ' \
+                               "#{DEFAULT_LIMIT}, e.g. 500."
+          },
+          execute: lambda { |path:, offset: 1, limit: DEFAULT_LIMIT|
+            FileindexRead.read(path: path, offset: offset, limit: limit, backend: backend)
+          },
+          # As {FileindexSearch}: whole-machine reach, so both inbound legs are fixed.
+          trifecta_legs: Pikuri::Tool::TrifectaLegs.new(private: true, untrusted: :hard, egress_payload_review: :no_egress)
+        )
+      end
+
+      # @param path [String]
+      # @param backend [Module] the file-index backend to read from
+      # @param offset [Integer] 1-indexed start line
+      # @param limit [Integer] max lines
+      # @return [String] the cat-n windowed text, or +"Error: ..."+
+      def self.read(path:, backend:, offset: 1, limit: DEFAULT_LIMIT)
+        return "Error: offset must be >= 1, got #{offset}" if offset < 1
+        return "Error: limit must be >= 1, got #{limit}"   if limit < 1
+
+        text = backend.read_text(path)
+        if text.nil?
+          return "Error: #{path} is not in the index (only indexed folders are " \
+                 'available; PDFs and office docs are included). For a live or ' \
+                 'system text file, use the read tool.'
+        end
+
+        page = Pikuri::Extractor.extract_paged(
+          StringIO.new(text), content_type: 'text/plain', offset: offset, limit: limit
+        )
+        render_page(page)
+      end
+
+      # Render a {Pikuri::Extractor::Page} as +cat -n+ + a paging trailer,
+      # mirroring {Pikuri::Workspace::Read}'s formatting.
+      #
+      # @param page [Pikuri::Extractor::Page]
+      # @return [String]
+      def self.render_page(page)
+        return '(No indexed text for this file.)' if page.total_lines.zero?
+
+        if page.lines.empty?
+          return "Error: offset #{page.start_line} is beyond end of file " \
+                 "(#{page.total_lines} lines total)"
+        end
+
+        last = page.start_line + page.lines.length - 1
+        body = page.lines.each_with_index
+                   .map { |line, i| format("%6d\t%s", i + page.start_line, line) }
+                   .join("\n")
+
+        trailer =
+          if page.byte_capped
+            "(Output capped at #{MAX_BYTES_LABEL}. Showing lines #{page.start_line}-#{last}. " \
+              "Use offset=#{last + 1} to continue.)"
+          elsif page.more
+            total = page.total_lines ? " of #{page.total_lines}" : ''
+            "(Showing lines #{page.start_line}-#{last}#{total}. Use offset=#{last + 1} to continue.)"
+          else
+            "(End of file - total #{page.total_lines} lines)"
+          end
+
+        "#{body}\n\n#{trailer}"
+      end
+      private_class_method :render_page
+    end
+  end
+end

data/lib/pikuri/os/fileindex_search.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Os
+    # The +fileindex_search+ tool — a fast, cheap keyword lookup over a
+    # desktop file index, returning matching paths each with the *single*
+    # snippet the index provides. A {Pikuri::Tool} in the
+    # {Pikuri::Workspace::Search::Grep} shape (shells out through the backend,
+    # fails loud at construction if the binary is missing).
+    #
+    # The +backend:+ is a stateless module satisfying the file-index duck
+    # type (see {#initialize}) — {LocalSearch} or {Recoll}, whichever
+    # {Extension} finds usable. Backend-specific text (the blind-spot note,
+    # the error label) is read from the backend, so a new index arm ships
+    # its own without touching the tool.
+    #
+    # It's a locator, not a window: the index reports at most one match per
+    # file, so the tool previews one match each and tells the LLM to read
+    # the file for full content / other matches. It sees inside PDFs and
+    # office docs (indexed at extract time), and being an index lookup is
+    # cheap to run repeatedly.
+    #
+    # Sharing: +P_stateless+ — the backend is a stateless module and each call
+    # shells out to its own query, so one instance serves any number of agents.
+    class FileindexSearch < Pikuri::Tool
+      # @return [Integer] default / max matching files returned.
+      DEFAULT_LIMIT = 10
+      MAX_LIMIT     = 25
+
+      # @return [Integer] hard byte cap on combined output (matches
+      #   {Pikuri::Workspace::Search::Grep::MAX_BYTES}).
+      MAX_BYTES = 50 * 1024
+
+      # @return [String] human-readable form of {MAX_BYTES}.
+      MAX_BYTES_LABEL = "#{MAX_BYTES / 1024} KB"
+
+      # @return [String] opencode-shape description (summary + Usage),
+      #   backend-neutral. The *runtime* tool description is this constant
+      #   plus the backend's +#limitations+, appended at construction (see
+      #   {#initialize}) — and it is that appended text, not this constant,
+      #   that states *which folders the index actually covers* and what it
+      #   misses (recoll lists its +topdirs+; localsearch notes it ranks
+      #   across the whole home). So keep coverage claims out of here; they
+      #   belong with the backend that knows them.
+      DESCRIPTION = <<~DESC
+        Find files whose contents contain your words or phrase, using the desktop search index.
+
+        Usage:
+        - Searches inside PDFs, Word/ODT/spreadsheet documents and plain text — reach for this when the answer may live in a file's contents.
+        - Keyword match (and word stems); type the actual words that would appear in the file.
+        - The index returns at most ONE match per file and may be slightly stale — this is a locator, not the full story. To read a file's full, current text, read it (see fileindex_read).
+        - Cheap: it queries a prebuilt index rather than walking the filesystem, so it barely touches the disk of the machine the user is on — fine to run many times to narrow down.
+        - Only indexed folders are covered; system paths like /etc or /var are not — search those with a text/regex tool instead.
+        - Output is truncated to #{MAX_BYTES_LABEL}; narrow the query if it ends in a truncation marker.
+      DESC
+
+      # @param backend [Module] a file-index backend ({LocalSearch} /
+      #   {Recoll}) — must respond to +#search+, +#read_text+,
+      #   +#check_binaries!+, +#limitations+, +#label+ and define a
+      #   +CommandError+.
+      # @raise [RuntimeError] if the backend's binary isn't on +PATH+.
+      # @return [FileindexSearch]
+      def initialize(backend:)
+        @backend = backend
+        backend.check_binaries!
+        super(
+          name: 'fileindex_search',
+          description: "#{DESCRIPTION}\n#{backend.limitations}",
+          parameters: Parameters.build { |p|
+            p.required_string :query,
+                              'Words or a phrase to find in file contents, ' \
+                              'e.g. "tax return 2024".'
+            p.optional_integer :limit,
+                               "Max number of matching files to return " \
+                               "(default #{DEFAULT_LIMIT}, max #{MAX_LIMIT}), e.g. 10."
+          },
+          execute: lambda { |query:, limit: DEFAULT_LIMIT|
+            FileindexSearch.search(query: query, limit: limit, backend: backend)
+          },
+          # Private and hard untrusted, both fixed rather than derived: this searches
+          # the *whole machine's* file index, which is the AllowAll case by
+          # construction — a reachable set nobody can vouch for, holding whatever the
+          # user keeps on disk.
+          trifecta_legs: Pikuri::Tool::TrifectaLegs.new(private: true, untrusted: :hard, egress_payload_review: :no_egress)
+        )
+      end
+
+      # @param query [String]
+      # @param limit [Integer]
+      # @param backend [Module] the file-index backend to query
+      # @return [String] formatted hits + disclaimer, a no-match message,
+      #   or +"Error: ..."+
+      def self.search(query:, backend:, limit: DEFAULT_LIMIT)
+        q = query.to_s.strip
+        return 'Error: empty query.' if q.empty?
+
+        limit = clamp(limit, 1, MAX_LIMIT)
+        hits = backend.search(query: q, limit: limit)
+        return no_match_message(q) if hits.empty?
+
+        content, marker = head_truncate(hits.map { |hit| render_hit(hit) }.join("\n"))
+        [content.chomp, '', disclaimer(hits.size) + marker].join("\n")
+      rescue backend::CommandError => e
+        # Cap the error too — a raw subprocess error returned verbatim is
+        # the shape that overflows the model's context; share the success
+        # path's ceiling.
+        content, marker = head_truncate(e.message)
+        "Error: #{backend.label}: #{content}#{marker}"
+      end
+
+      # @return [String] +"<path>"+ or +"<path>\n  <snippet>"+
+      def self.render_hit(hit)
+        hit[:snippet] && !hit[:snippet].empty? ? "#{hit[:path]}\n  #{hit[:snippet]}" : hit[:path]
+      end
+      private_class_method :render_hit
+
+      # @return [String]
+      def self.disclaimer(count)
+        "Found #{count} #{count == 1 ? 'file' : 'files'} (one match shown per file; " \
+          'the index may be slightly stale). Read a file to see its full text and any other matches.'
+      end
+      private_class_method :disclaimer
+
+      # @return [String]
+      def self.no_match_message(query)
+        "No files found matching '#{query}'. (Searches your indexed folders, " \
+          'not system paths; the index may also be disabled or still building.)'
+      end
+      private_class_method :no_match_message
+
+      # Head-truncate to {MAX_BYTES} at the last newline boundary.
+      #
+      # @return [Array(String, String)] +[content, marker]+ (marker empty
+      #   when no truncation)
+      def self.head_truncate(raw)
+        total = raw.bytesize
+        return [raw, ''] if total <= MAX_BYTES
+
+        head = raw.byteslice(0, MAX_BYTES)
+        last_nl = head.rindex("\n")
+        head = head.byteslice(0, last_nl) if last_nl
+        omitted = total - head.bytesize
+        [head, "\n\n... [#{omitted} bytes omitted; total was #{total} bytes; narrow the query] ..."]
+      end
+      private_class_method :head_truncate
+
+      # @return [Integer] +value+ clamped to +[lo, hi]+ (lo on bad input)
+      def self.clamp(value, lo, hi)
+        Integer(value).clamp(lo, hi)
+      rescue ArgumentError, TypeError
+        lo
+      end
+      private_class_method :clamp
+    end
+  end
+end