kward 0.83.0 → 0.85.0

data/lib/kward/config/prompts.rb

@@ -0,0 +1,313 @@
+# Configuration prompts behavior.
+module Kward
+  module ConfigFiles
+    module Prompts
+      extend self
+
+      def agents_prompt(config: read_config)
+        return nil unless include_config_principles?(config)
+
+        path = config_principles_path
+        return read_prompt_file(path, "Kward principles file") if File.exist?(path)
+
+        read_prompt_file(config_agents_path, "Kward AGENTS.md alias")
+      end
+
+      # Returns whether config-directory principles are included in normal system
+      # prompt assembly. Replacement prompt files bypass all assembled sections.
+      def include_config_principles?(config = read_config)
+        settings = config["system_prompt"]
+        return true unless settings.is_a?(Hash)
+
+        settings["include_principles"] != false
+      end
+
+      # Returns the configured replacement system prompt path, or nil when normal
+      # prompt assembly should be used. Relative paths are anchored to the config
+      # directory so configuration remains portable with KWARD_CONFIG_PATH.
+      def system_prompt_file_path(config = read_config)
+        settings = config["system_prompt"]
+        value = settings.is_a?(Hash) ? settings["file"].to_s.strip : ""
+        return nil if value.empty?
+
+        File.expand_path(value, config_dir)
+      end
+
+      # Returns the replacement system prompt text when configured. A configured
+      # but unavailable file intentionally yields nil: callers must not fall back
+      # to Kward's larger assembled prompt in replacement mode.
+      def system_prompt_file(config = read_config)
+        path = system_prompt_file_path(config)
+        return nil unless path
+
+        read_prompt_file(path, "custom system prompt file")
+      end
+
+      def replacement_system_prompt?(config = read_config)
+        !system_prompt_file_path(config).nil?
+      end
+
+      # Returns a lightweight fingerprint for config-owned prompt sources. It is
+      # used by active conversations to pick up prompt edits without a restart.
+      def system_prompt_sources_fingerprint
+        config = read_config
+        paths = [config_path, system_prompt_file_path(config)]
+        if include_config_principles?(config)
+          paths << (File.exist?(config_principles_path) ? config_principles_path : config_agents_path)
+        end
+
+        paths.compact.map { |path| prompt_source_signature(path) }.join("\0")
+      end
+
+      def config_principles_path
+        File.join(config_dir, "PRINCIPLES.md")
+      end
+
+      def config_agents_path
+        File.join(config_dir, "AGENTS.md")
+      end
+
+      # Builds persona prompt text from default, workspace, model, reasoning,
+      # time-of-day, weekday, and suffix config entries.
+      #
+      # Persona resolution is intentionally data-driven so users can edit config
+      # without plugin code. Keep new persona selectors additive and deterministic;
+      # prompt construction depends on stable ordering.
+      #
+      # @param workspace_root [String] active workspace root
+      # @param model [String, nil] active model name
+      # @param reasoning_effort [String, nil] active reasoning effort
+      # @param now [Time] local time used for time-based modifiers
+      # @param config [Hash] parsed config object
+      # @return [String, nil] persona prompt text when entries match
+      def persona_prompt(workspace_root, model: nil, reasoning_effort: nil, now: Time.now, config: read_config)
+        text = persona_entries(workspace_root: workspace_root, model: model, reasoning_effort: reasoning_effort, now: now, config: config).map do |entry|
+          entry[:prompt]
+        end.join("\n\n")
+        return nil if text.empty?
+
+        text
+      end
+
+      # Returns the label of the persona selected by default/workspace/model rules.
+      def active_persona_label(workspace_root:, model: nil, config: read_config)
+        personas = config["personas"]
+        return nil unless personas.is_a?(Hash)
+
+        labels = crew_character_labels(personas)
+        active_label = persona_label_for_key(personas["default"], labels) unless personas["default"].nil?
+
+        workspaces = personas["workspaces"]
+        if workspaces.is_a?(Hash)
+          root = canonical_workspace_root(workspace_root)
+          workspaces.each do |path, key|
+            next unless canonical_workspace_root(path) == root
+
+            active_label = persona_label_for_key(key, labels)
+            break
+          end
+        end
+
+        models = personas["models"]
+        if models.is_a?(Hash) && !model.to_s.empty? && models.key?(model.to_s)
+          active_label = persona_label_for_key(models[model.to_s], labels)
+        end
+
+        active_label
+      end
+
+      def persona_entries(workspace_root:, model: nil, reasoning_effort: nil, now: Time.now, config: read_config, include_reasoning: true)
+        personas = config["personas"]
+        return [] unless personas.is_a?(Hash)
+
+        characters = crew_characters(personas)
+        entries = []
+        active_persona = { layer: "default", value: personas["default"], name: nil }
+
+        workspaces = personas["workspaces"]
+        if workspaces.is_a?(Hash)
+          root = canonical_workspace_root(workspace_root)
+          workspaces.each do |path, key|
+            if canonical_workspace_root(path) == root
+              active_persona = { layer: "workspace", value: key, name: path }
+              break
+            end
+          end
+        end
+
+        models = personas["models"]
+        if models.is_a?(Hash) && !model.to_s.empty? && models.key?(model.to_s)
+          active_persona = { layer: "model", value: models[model.to_s], name: model.to_s }
+        end
+
+        add_persona_entry(
+          entries,
+          active_persona.fetch(:layer),
+          resolved_persona_text(active_persona.fetch(:value), characters: characters),
+          name: active_persona[:name]
+        )
+
+        modifiers = personas["persona_modifiers"]
+        if modifiers.is_a?(Hash)
+          if include_reasoning
+            reasoning = modifiers["reasoning"]
+            add_persona_entry(entries, "reasoning", reasoning[reasoning_effort.to_s]) if reasoning.is_a?(Hash) && !reasoning_effort.to_s.empty?
+          end
+
+          time_of_day = modifiers["time_of_day"]
+          bucket = time_of_day_bucket(now)
+          add_persona_entry(entries, "time_of_day", time_of_day[bucket], name: bucket) if time_of_day.is_a?(Hash)
+
+          weekday = modifiers["weekday"]
+          day = weekday_name(now)
+          add_persona_entry(entries, "weekday", weekday[day], name: day) if weekday.is_a?(Hash)
+
+          add_persona_entry(entries, "suffix", modifiers["suffix"])
+        end
+
+        entries
+      end
+
+      def workspace_agents_path(workspace_root)
+        File.join(canonical_workspace_root(workspace_root), "AGENTS.md")
+      end
+
+      def workspace_agents_file?(workspace_root)
+        File.exist?(workspace_agents_path(workspace_root))
+      end
+
+      def workspace_agents_prompt(workspace_root)
+        read_prompt_file(workspace_agents_path(workspace_root), "workspace AGENTS.md")
+      end
+
+      def prompt_source_signature(path)
+        return "#{path}:missing" unless File.exist?(path)
+
+        stat = File.stat(path)
+        "#{path}:#{stat.size}:#{stat.mtime.to_f}"
+      rescue StandardError
+        "#{path}:unavailable"
+      end
+
+      def read_prompt_file(path, label)
+        return nil unless File.exist?(path)
+
+        size = File.size(path)
+        if size > MAX_PROMPT_FILE_BYTES
+          emit_warning "Warning: skipping #{label} #{path}: file too large (#{size} bytes; limit is #{MAX_PROMPT_FILE_BYTES} bytes)"
+          return nil
+        end
+
+        File.read(path)
+      rescue StandardError => e
+        emit_warning "Warning: skipping #{label} #{path}: #{e.message}"
+        nil
+      end
+
+      def canonical_workspace_root(path)
+        expanded = File.expand_path(path.to_s.empty? ? Dir.pwd : path.to_s)
+        File.directory?(expanded) ? File.realpath(expanded) : expanded
+      end
+
+      def add_persona_entry(entries, layer, value, name: nil)
+        text = presence(value)
+        return unless text
+
+        entries << { layer: layer.to_s, name: name.to_s, prompt: text }
+      end
+
+      def crew_characters(personas)
+        named_character_values(personas) do |_key, definition|
+          extract_character_instruction(definition)
+        end
+      end
+
+      def crew_character_labels(personas)
+        named_character_values(personas) do |_key, definition|
+          extract_character_label(definition)
+        end
+      end
+
+      def resolved_persona_text(value, characters: {})
+        return nil if value.nil?
+
+        key = value.to_s.strip
+        return nil if key.empty?
+
+        text = characters[key.to_s]
+        return text unless text.to_s.empty?
+
+        value
+      end
+
+      def persona_label_for_key(value, labels)
+        key = value.to_s.strip
+        return nil if key.empty?
+
+        presence(labels[key])
+      end
+
+      def named_character_values(personas)
+        character_entries(personas["characters"] || personas["crew"]).each_with_object({}) do |(key, definition), mapping|
+          value = yield(key, definition)
+          next if value.to_s.empty?
+
+          mapping[key.to_s] = value
+        end
+      end
+
+      def character_entries(raw)
+        case raw
+        when Hash
+          raw.map { |key, definition| [key, definition] }
+        when Array
+          raw.filter_map { |entry| character_entry(entry) }
+        else
+          []
+        end
+      end
+
+      def character_entry(entry)
+        return nil unless entry.is_a?(Hash)
+
+        if entry.length == 1 && entry.keys.first.is_a?(String)
+          [entry.keys.first, entry.values.first]
+        else
+          key = entry["key"] || entry[:key] || entry["id"] || entry[:id] || entry["name"] || entry[:name]
+          key.to_s.empty? ? nil : [key, entry]
+        end
+      end
+
+      def extract_character_label(definition)
+        return nil unless definition.is_a?(Hash)
+
+        presence(definition["label"] || definition[:label])
+      end
+
+      def extract_character_instruction(definition)
+        return nil if definition.nil?
+
+        if definition.is_a?(Hash)
+          value = definition["instruction"] || definition[:instruction]
+          return presence(value)
+        end
+
+        presence(definition)
+      end
+
+      def time_of_day_bucket(now)
+        hour = now.hour
+        return "morning" if hour >= 5 && hour < 11
+        return "before_lunch" if hour == 11
+        return "late_evening" if hour >= 21 || hour < 5
+
+        nil
+      end
+
+      def weekday_name(now)
+        %w[sunday monday tuesday wednesday thursday friday saturday][now.wday]
+      end
+
+    end
+  end
+end

data/lib/kward/config/settings.rb

@@ -0,0 +1,250 @@
+# Configuration settings behavior.
+module Kward
+  module ConfigFiles
+    module Settings
+      extend self
+
+      def overlay_settings(config = read_config)
+        overlay = config["overlay"].is_a?(Hash) ? config["overlay"] : {}
+        settings = DEFAULT_OVERLAY_SETTINGS.dup
+        alignment = overlay["alignment"].to_s
+        width = overlay["width"].to_s
+        settings["alignment"] = alignment if OVERLAY_ALIGNMENTS.include?(alignment)
+        settings["width"] = width if OVERLAY_WIDTHS.include?(width)
+        settings
+      end
+
+      # Returns the project browser icon theme, or off when unset or invalid.
+      def project_browser_icon_theme(config = read_config)
+        browser = config["project_browser"].is_a?(Hash) ? config["project_browser"] : {}
+        theme = browser["icons"].to_s
+        PROJECT_BROWSER_ICON_THEMES.include?(theme) ? theme : "off"
+      end
+
+      # Returns whether the composer should show busy-state keyboard help.
+      def composer_busy_help?(config = read_config)
+        composer = config["composer"].is_a?(Hash) ? config["composer"] : {}
+        composer["busy_help"] != false
+      end
+
+      # Returns the configured tab keybinding family, or auto when unset/invalid.
+      def composer_tab_keybindings(config = read_config)
+        composer = config["composer"].is_a?(Hash) ? config["composer"] : {}
+        value = composer["tab_keybindings"].to_s.downcase
+        %w[auto ctrl alt].include?(value) ? value : "auto"
+      end
+
+      # Returns the built-in TUI editor keymap mode.
+      def editor_mode(config = read_config)
+        editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
+        EditorMode.normalize(editor["mode"])
+      end
+
+      # Returns configured editor runner definitions, or an empty map.
+      #
+      # Runner defaults are resolved by the editor runner at execution time so
+      # the generated config remains portable across machines.
+      def editor_runners(config = read_config)
+        editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
+        runners = editor["runners"]
+        runners.is_a?(Hash) ? runners : {}
+      end
+
+      # Returns the optional provider override for editor-agent turns.
+      def editor_agent_provider(config = read_config)
+        value = ENV["KWARD_EDITOR_PROVIDER"].to_s.strip
+        return value unless value.empty?
+
+        editor_agent_setting(config, "provider")
+      end
+
+      # Returns the optional model override for editor-agent turns.
+      def editor_agent_model(config = read_config)
+        editor_agent_setting(config, "model")
+      end
+
+      # Returns the optional reasoning-effort override for editor-agent turns.
+      def editor_agent_reasoning_effort(config = read_config)
+        editor_agent_setting(config, "reasoning_effort")
+      end
+
+      # Returns the shell-agent provider override, preferring the environment.
+      def shell_agent_provider(config = read_config)
+        value = ENV["KWSH_PROVIDER"].to_s.strip
+        return value unless value.empty?
+
+        shell_agent_setting(config, "provider")
+      end
+
+      # Returns the shell-agent model override, preferring the environment.
+      def shell_agent_model(config = read_config)
+        value = ENV["KWSH_MODE"].to_s.strip
+        return value unless value.empty?
+
+        shell_agent_setting(config, "model")
+      end
+
+      # Returns the shell-agent reasoning-effort override, preferring the environment.
+      def shell_agent_reasoning_effort(config = read_config)
+        value = ENV["KWSH_REASONING"].to_s.strip
+        return value unless value.empty?
+
+        shell_agent_setting(config, "reasoning_effort")
+      end
+
+      def editor_agent_setting(config, key)
+        editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
+        agent = editor["agent"].is_a?(Hash) ? editor["agent"] : {}
+        value = agent[key].to_s.strip
+        value.empty? ? nil : value
+      end
+
+      def shell_agent_setting(config, key)
+        shell = config["shell"].is_a?(Hash) ? config["shell"] : {}
+        agent = shell["agent"].is_a?(Hash) ? shell["agent"] : {}
+        value = agent[key].to_s.strip
+        value.empty? ? nil : value
+      end
+
+      # Returns whether the built-in TUI editor should auto-indent new lines.
+      def editor_auto_indent?(config = read_config)
+        editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
+        editor["auto_indent"] != false
+      end
+
+      # Returns whether the built-in TUI editor should auto-close typed pairs.
+      def editor_auto_close_pairs?(config = read_config)
+        editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
+        editor["auto_close_pairs"] != false
+      end
+
+      # Returns whether the built-in TUI editor should soft-wrap long lines.
+      def editor_soft_wrap?(config = read_config)
+        editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
+        editor["soft_wrap"] != false
+      end
+
+      # Returns whether editable built-in TUI editor buffers should use a bar cursor.
+      def editor_bar_cursor?(config = read_config)
+        editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
+        editor["bar_cursor"] != false
+      end
+
+      # Returns the built-in TUI editor line-number display mode.
+      def editor_line_numbers(config = read_config)
+        editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
+        EditorMode.normalize_line_numbers(editor["line_numbers"])
+      end
+
+      # Returns the integrated diff viewer display mode.
+      def diff_view(config = read_config)
+        editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
+        DiffViewMode.normalize(editor["diff_view"])
+      end
+
+      # Returns whether file tools must stay inside the active workspace root.
+      def workspace_guardrails_enabled?(config = read_config)
+        tools = config["tools"].is_a?(Hash) ? config["tools"] : {}
+        tools["workspace_guardrails"] != false
+      end
+
+      # Builds the opt-in model-tool permission policy from persisted configuration.
+      def permission_policy(config = read_config)
+        Permissions::Policy.from_config(config)
+      end
+
+      # Builds the user-controlled command sandbox policy for a workspace.
+      def sandbox_policy(workspace_root, config = read_config)
+        sandbox = config["sandbox"].is_a?(Hash) ? config["sandbox"] : {}
+        Sandbox::Policy.new(
+          mode: sandbox.fetch("mode", "off"),
+          network: sandbox.fetch("network", "deny"),
+          workspace_root: workspace_root,
+          writable_roots: sandbox.fetch("writable_roots", []),
+          protect_git_metadata: sandbox.fetch("protect_git_metadata", true)
+        )
+      end
+
+      # Returns whether project-level Agent Skills should be loaded from the workspace.
+      def project_skills_trusted?(config = read_config)
+        skills = config["skills"].is_a?(Hash) ? config["skills"] : {}
+        skills["trust_project"] == true
+      end
+
+      # Returns whether new frontends should resume the last active session automatically.
+      def session_auto_resume_enabled?(config = read_config)
+        sessions = config["sessions"].is_a?(Hash) ? config["sessions"] : {}
+        sessions["auto_resume"] == true
+      end
+
+      # Returns whether workspace AGENTS.md contents should be injected directly
+      # instead of a compact read-when-relevant instruction.
+      def enforce_workspace_agents_file?(config = read_config)
+        config["enforce_workspace_agents_file"] == true
+      end
+
+      # Returns the nested web-search config object, or an empty config when absent.
+      def web_search_config(config = read_config)
+        value = config["web_search"]
+        value.is_a?(Hash) ? value : {}
+      end
+
+      # Returns the private configuration namespace for one identified plugin.
+      def plugin_config(plugin_id, config = read_config)
+        plugins = config.fetch("plugins", {})
+        raise ArgumentError, "Kward plugin config must be an object" unless plugins.is_a?(Hash)
+
+        values = plugins.fetch(plugin_id.to_s, {})
+        raise ArgumentError, "Kward plugin config for #{plugin_id} must be an object" unless values.is_a?(Hash)
+
+        DeepCopy.dup(values)
+      end
+
+      # Returns the private configuration namespace for one transport.
+      def transport_config(transport_id, config = read_config)
+        transports = config["transports"]
+        return {} unless transports.is_a?(Hash)
+
+        values = transports[transport_id.to_s]
+        values.is_a?(Hash) ? DeepCopy.dup(values) : {}
+      end
+
+      # Returns configured MCP stdio servers, or an empty config when absent.
+      def mcp_servers(config = read_config)
+        value = config["mcpServers"] || config.dig("mcp", "servers")
+        value.is_a?(Hash) ? value : {}
+      end
+
+      # Validates and persists terminal overlay settings.
+      def update_overlay_settings(values)
+        raise "Overlay settings must be an object" unless values.is_a?(Hash)
+
+        config = read_config
+        overlay = overlay_settings(config)
+        values.each do |key, value|
+          key = key.to_s
+          value = value.to_s
+          case key
+          when "alignment"
+            raise "Overlay alignment must be left, center, or right" unless OVERLAY_ALIGNMENTS.include?(value)
+          when "width"
+            raise "Overlay width must be capped or maximum" unless OVERLAY_WIDTHS.include?(value)
+          else
+            raise "Unknown overlay setting: #{key}"
+          end
+          overlay[key] = value
+        end
+        config["overlay"] = overlay
+        write_config(config)
+        overlay_settings(config)
+      end
+
+      # Reads global principle instructions from the config directory.
+      #
+      # `PRINCIPLES.md` is preferred. `AGENTS.md` remains a backwards-compatible
+      # alias for existing installations.
+      #
+      # @return [String, nil] prompt text, or nil when absent/too large
+    end
+  end
+end