pikuri-os 0.1.0

data/lib/pikuri/os/system_info.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'etc'
+
+module Pikuri
+  module Os
+    # Boot-time machine facts for the OS helper: a small block folded into
+    # the system prompt so the model doesn't guess the distro, init system,
+    # or paths. Narrative in book/os-assistant.md.
+    #
+    # The core facts (distro, kernel, init, packaging, desktop, CPU/mem,
+    # home, shell, dmesg access, date) come from **always-present
+    # primitives** — +Etc+, +/etc/os-release+, +/proc+, +ENV+, a +$PATH+
+    # probe — so the block is deterministic, needs no external binary, and
+    # works headless or in CI. The dmesg line is read from
+    # +kernel.dmesg_restrict+ (not by spawning +dmesg+) so the model knows
+    # up front whether the kernel log is readable. When +inxi+ is present,
+    # +inxi -b+ output is appended as extra hardware/desktop detail; it is
+    # enrichment, never a dependency — a missing or failing +inxi+ is never
+    # fatal.
+    #
+    # A read-once-at-boot snapshot (the date is "at startup"). The host
+    # doesn't change distro mid-session, and {#prompt_section} is
+    # **memoized** so the +inxi+ subprocess runs once no matter how often
+    # the prompt is re-assembled. Unlike {MachineMemory}, this deliberately
+    # does *not* refresh on {Pikuri::Agent#clear_conversation}.
+    class SystemInfo
+      # @return [Integer] cap on the appended +inxi -b+ block, so a chatty
+      #   inxi can't bloat the prompt.
+      INXI_MAX_BYTES = 4 * 1024
+
+      # Native package managers, in detection order: +[command, distro
+      # hint]+. The first on +$PATH+ wins and is reported as this host's
+      # primary manager. flatpak/snap are detected separately (cross-distro,
+      # can coexist) — see {#packaging}.
+      NATIVE_PACKAGE_MANAGERS = [
+        ['apt',          'Debian/Ubuntu, dpkg'],
+        ['dnf',          'Fedora/RHEL, rpm'],
+        ['yum',          'RHEL/CentOS, rpm'],
+        ['zypper',       'openSUSE, rpm'],
+        ['pacman',       'Arch'],
+        ['apk',          'Alpine'],
+        ['xbps-install', 'Void'],
+        ['emerge',       'Gentoo, portage'],
+        ['eopkg',        'Solus']
+      ].freeze
+
+      # Ordered (fact-key, label) pairs for {.render}. A +nil+ value is
+      # skipped, so a fact we couldn't read just doesn't appear.
+      FACT_ORDER = [
+        [:os,        'OS'],
+        [:kernel,    'Kernel'],
+        [:init,      'Init'],
+        [:packaging, 'Packaging'],
+        [:desktop,   'Desktop'],
+        [:hostname,  'Hostname'],
+        [:home,      'Home'],
+        [:shell,     'Shell'],
+        [:cpus,      'CPUs'],
+        [:memory,    'Memory'],
+        [:dmesg,     'Kernel log (dmesg)'],
+        [:date,      'Date (at startup)']
+      ].freeze
+
+      # The system-prompt grounding section: a +# This machine+ heading,
+      # a one-line "trust these over your guesses" nudge, the core facts,
+      # and (when +inxi+ is present) an extra-detail block.
+      # Memoized (see class doc).
+      #
+      # @return [String]
+      def prompt_section
+        @prompt_section ||= begin
+          parts = ['# This machine', '',
+                   'Rely on these facts rather than guessing the distro, paths, or init system.',
+                   '', self.class.render(facts)]
+          detail = inxi_detail
+          parts += ['', 'Further hardware/desktop detail (from `inxi -b`):', detail] if detail
+          parts.join("\n")
+        end
+      end
+
+      # Render a facts hash as +"- Label: value"+ lines in {FACT_ORDER},
+      # skipping keys with no value. Pure — the testable core.
+      #
+      # @param facts [Hash{Symbol=>Object}]
+      # @return [String]
+      def self.render(facts)
+        FACT_ORDER.filter_map do |key, label|
+          value = facts[key]
+          "- #{label}: #{value}" unless value.nil? || value.to_s.strip.empty?
+        end.join("\n")
+      end
+
+      # The core facts, each gathered best-effort (a reader that fails
+      # yields +nil+ and the line is dropped).
+      #
+      # @return [Hash{Symbol=>Object}]
+      def facts
+        {
+          os:        os_pretty_name,
+          kernel:    kernel_string,
+          init:      init_system,
+          packaging: packaging,
+          desktop:   presence(ENV['XDG_CURRENT_DESKTOP']),
+          hostname:  uname[:nodename],
+          home:      home_dir,
+          shell:     presence(ENV['SHELL']),
+          cpus:      cpu_count,
+          memory:    total_memory,
+          dmesg:     dmesg_access,
+          date:      Time.now.strftime('%Y-%m-%d %H:%M:%S %z')
+        }
+      end
+
+      private
+
+      # The host's package-management surface: the primary native manager
+      # (first {NATIVE_PACKAGE_MANAGERS} entry on +$PATH+, with its distro
+      # hint) followed by whichever of flatpak / snap are installed, e.g.
+      # +"apt (Debian/Ubuntu, dpkg); flatpak"+. +nil+ when none are found
+      # (so the line is dropped rather than asserting a bare box has no way
+      # to install software).
+      #
+      # @return [String, nil]
+      def packaging
+        native = NATIVE_PACKAGE_MANAGERS.find { |cmd, _| on_path?(cmd) }
+        parts = []
+        parts << "#{native[0]} (#{native[1]})" if native
+        parts << 'flatpak' if on_path?('flatpak')
+        parts << 'snap' if on_path?('snap')
+        parts.empty? ? nil : parts.join('; ')
+      end
+
+      # Whether this user can read the kernel ring buffer (+dmesg+), decided
+      # from +kernel.dmesg_restrict+ rather than by spawning +dmesg+ — so
+      # the model knows in advance whether a +dmesg+ call returns logs or
+      # fails with "read kernel buffer failed: Operation not permitted".
+      # +nil+ (line dropped) when +dmesg+ isn't installed.
+      #
+      # @return [String, nil]
+      def dmesg_access
+        return nil unless on_path?('dmesg')
+        return 'readable (running as root)' if Process.uid.zero?
+
+        case File.read('/proc/sys/kernel/dmesg_restrict').strip
+        when '0' then 'readable'
+        when '1' then 'restricted as this user — needs sudo (kernel.dmesg_restrict=1)'
+        end
+      rescue SystemCallError
+        # dmesg_restrict absent on this kernel: unprivileged reads are the
+        # historical default, so treat it as readable rather than guessing.
+        'likely readable (kernel.dmesg_restrict unset)'
+      end
+
+      # @param name [String] a bare command name, e.g. "flatpak"
+      # @return [Boolean] true if an executable by that name is on +$PATH+
+      def on_path?(name)
+        ENV['PATH'].to_s.split(File::PATH_SEPARATOR).any? do |dir|
+          next false if dir.empty?
+
+          path = File.join(dir, name)
+          File.file?(path) && File.executable?(path)
+        end
+      end
+
+      # +inxi -b -c 0+ output (color stripped) when inxi is on PATH, capped
+      # to {INXI_MAX_BYTES}; +nil+ when inxi is absent, errors, or is
+      # empty. Never raises out — enrichment only.
+      #
+      # @return [String, nil]
+      def inxi_detail
+        result = Pikuri::Subprocess.spawn('inxi', '-b', '-c', '0', chdir: '/').wait
+        return nil unless result.status.success?
+
+        out = result.output.strip
+        return nil if out.empty?
+
+        out.bytesize > INXI_MAX_BYTES ? "#{out.byteslice(0, INXI_MAX_BYTES)}\n…" : out
+      rescue Errno::ENOENT
+        nil
+      end
+
+      # @return [String, nil] +PRETTY_NAME+ from +/etc/os-release+
+      def os_pretty_name
+        line = File.foreach('/etc/os-release').find { |l| l.start_with?('PRETTY_NAME=') }
+        return nil unless line
+
+        line.split('=', 2).last.strip.delete_prefix('"').delete_suffix('"')
+      rescue SystemCallError
+        nil
+      end
+
+      # @return [String, nil] +"<release> <machine>"+, e.g. "7.0.0-27-generic x86_64"
+      def kernel_string
+        u = uname
+        return nil unless u[:release]
+
+        [u[:release], u[:machine]].compact.join(' ')
+      end
+
+      # @return [Hash] memoized +Etc.uname+ (sysname/nodename/release/…),
+      #   or +{}+ if unavailable.
+      def uname
+        @uname ||= (Etc.uname rescue {})
+      end
+
+      # @return [String, nil] PID 1's command (e.g. "systemd")
+      def init_system
+        presence(File.read('/proc/1/comm').strip)
+      rescue SystemCallError
+        nil
+      end
+
+      # @return [String, nil]
+      def home_dir
+        Dir.home
+      rescue ArgumentError
+        presence(ENV['HOME'])
+      end
+
+      # @return [Integer, nil]
+      def cpu_count
+        Etc.nprocessors
+      rescue StandardError
+        nil
+      end
+
+      # @return [String, nil] total RAM, e.g. "23.5 GiB", from /proc/meminfo
+      def total_memory
+        line = File.foreach('/proc/meminfo').find { |l| l.start_with?('MemTotal:') }
+        return nil unless line
+
+        kb = line[/(\d+)/, 1]&.to_i
+        return nil unless kb
+
+        format('%.1f GiB', kb / 1024.0 / 1024.0)
+      rescue SystemCallError
+        nil
+      end
+
+      # @return [String, nil] +value+ unless nil/blank
+      def presence(value)
+        value && !value.to_s.strip.empty? ? value : nil
+      end
+    end
+  end
+end

data/lib/pikuri-os.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'pikuri-core'
+require 'pikuri-workspace'
+require 'pikuri-code'
+
+# Entry file for the pikuri-os gem: the OS-integration layer and home of
+# the +bin/pikuri-os+ demo — a single, local, network-severed
+# agent for understanding and operating the host OS ({Pikuri::Os::Extension}
+# is the one-call wiring). The load-bearing posture: egress severed at the
+# kernel (a net-isolated Bash sandbox), every mutation confirmed, durable
+# memory a user-owned +MACHINE.md+ rather than mem0 — so this gem depends
+# on pikuri-code but NOT pikuri-mcp/-memory/-vectordb. The two cross-cutting
+# pieces (+FullFsNoNet+ sandbox, passive-command detector) live in
+# pikuri-code with the other OS-touching primitives. Design notes:
+# +pikuri-os/DESIGN.md+ (the file-index engine survey) and
+# book/os-assistant.md (the security narrative).
+Pikuri::PROMPT_DIRS << File.expand_path('../prompts', __dir__)
+
+module Pikuri
+  module Os
+    LOADER = Zeitwerk::Loader.new
+    LOADER.tag = 'pikuri-os'
+    LOADER.push_dir(__dir__)
+    LOADER.ignore(File.expand_path('pikuri-os.rb', __dir__))
+    LOADER.setup
+    LOADER.eager_load
+  end
+end

data/prompts/os-assistant.txt

@@ -0,0 +1,13 @@
+You are a local assistant for this Linux machine. You help the user understand and operate the computer they are sitting at: answer questions about the system, find and open their files, read logs and explain what went wrong, and advise on configuration. This is a standard Linux system whose filesystem is organized according to the FHS (Filesystem Hierarchy Standard), so system files live in their conventional locations.
+
+How you operate:
+- You act on the *real* host, and you run as the ordinary (non-root) user.
+- You can't elevate privileges (no working sudo/su). A command that fails with `Permission denied`, `Operation not permitted`, or `are you root?` means the real answer needs root: hand the user the exact `sudo …` command and explain what it does — the same hand-off you use for anything needing the network. If that command *reads* something, ask them to paste the output back. If it *changes* the machine (installs a package, edits a system file, restarts a service), ask them only to say when it's done, then confirm the result yourself with the commands you can already run — don't make them paste output you don't need.
+- Network: the shell and the programs you run cannot reach the internet — you can't fetch a URL, install or update packages, or run a connectivity test. That's a property of your tools, not of the machine: it's a normal, networked computer and the user's own connectivity is fine, so never tell them their machine is offline, and don't read a failed fetch of your own as an outage on their end. When something genuinely needs the network — a download, an install, a reachability check — hand the user the exact command to run themselves (the same hand-off as anything needing root). Don't claim to have looked something up online unless you actually did.
+- Look, don't guess. When you're unsure of a path, a flag, or the current state of something, inspect the machine — read the file, list the directory, check the log — rather than assuming. The installed documentation is authoritative and beats a half-remembered flag: run `man <cmd>` or `<cmd> --help` for a command's exact options — especially for an unfamiliar, vendor, or locally-installed tool, or when behavior may differ by version — and `apropos <keyword>` (or `man -k`) to find which utility does something when you don't know its name. A package's own `/usr/share/doc/<pkg>/` often holds a README or examples.
+- To find a file (or which file mentions something) anywhere on this machine, search the desktop file index first — it reads inside PDFs and office documents a raw scan can't, and it's cheap to query. Reach for a content/filename scan of a directory tree only once you've narrowed to a specific place to look.
+
+Keeping notes: you keep durable notes about this machine (where the user keeps their music, work, and documents; how things are synced; quirks of this setup). When you learn a lasting fact like that, record it by editing the notes file named below, so a future conversation starts already knowing it. Keep the notes accurate and trim what's no longer true.
+
+Other guidelines:
+- When you have enough to answer, answer. Show the commands you'd run or did run, and cite file paths so the user can follow along. Give one clear recommendation with its reason rather than listing every option.

data/prompts/os-network-online.txt

@@ -0,0 +1,7 @@
+You have one exception to the no-network rule: for a genuine external lookup
+(current documentation, a library version, the meaning of an error seen online)
+you may delegate a self-contained research task to the web-capable research
+agent. It runs in isolation with no access to this machine's files, and the
+user approves the exact task before it leaves the machine — so write each task
+to stand on its own, put nothing private in it, and treat it as a way to *read*
+the web, never to act on this machine.

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: pikuri-os
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Martin Vysny
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pikuri-code
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: pikuri-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: pikuri-pdf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: pikuri-subagents
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: pikuri-workspace
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: |
+  pikuri-os is the OS-integration layer for pikuri and the home of
+  the +bin/pikuri-os+ demo: 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 standalone — no egress, no MCP, no cloud.
+
+  The gem holds the OS-specific surface (a localsearch-backed
+  content-search tool, a single-file +MACHINE.md+ resident memory,
+  and boot-time machine grounding) on top of pikuri-core's Agent +
+  Tool framework, pikuri-workspace's file tools, and pikuri-code's
+  Bash + sandbox. It deliberately does NOT depend on
+  pikuri-mcp/-memory/-vectordb: severing those keeps the no-egress,
+  "small enough to audit" posture honest.
+
+  See +ideas/pikuri-os.md+ in the repo for the full design.
+email:
+- martin@vysny.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/pikuri-os.rb
+- lib/pikuri/os/extension.rb
+- lib/pikuri/os/fileindex_read.rb
+- lib/pikuri/os/fileindex_search.rb
+- lib/pikuri/os/local_search.rb
+- lib/pikuri/os/machine_memory.rb
+- lib/pikuri/os/recoll.rb
+- lib/pikuri/os/system_info.rb
+- prompts/os-assistant.txt
+- prompts/os-network-online.txt
+homepage: https://codeberg.org/mvysny/pikuri
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://codeberg.org/mvysny/pikuri/src/branch/master
+  changelog_uri: https://codeberg.org/mvysny/pikuri/src/branch/master/CHANGELOG.md
+  bug_tracker_uri: https://codeberg.org/mvysny/pikuri/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Offline Linux/OS helper agent + tools for pikuri.
+test_files: []