kward 0.67.1 → 0.69.0

data/lib/kward/prompts/commands.rb

@@ -1,6 +1,8 @@
 require_relative "../config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Prompt-template and slash-command parsing helpers.
   module PromptCommands
     BUILTIN_COMMANDS = [
       { name: "exit", description: "Exit the interactive session.", argument_hint: "" },

data/lib/kward/prompts/templates.rb

@@ -1,5 +1,8 @@
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Prompt template discovery from configured markdown files.
   module Prompts
+    # Parsed prompt template loaded from disk.
     class Templates
       def initialize(config_dir:, template_class:, markdown_parser:)
         @config_dir = config_dir

data/lib/kward/prompts.rb

@@ -1,6 +1,8 @@
 require_relative "config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # System prompt assembly from config, workspace instructions, memory, and plugins.
   module Prompts
     module_function
 
@@ -12,18 +14,27 @@ module Kward
     end
 
     def prompt_parts(workspace_root: Dir.pwd, include_workspace_personality: true, model: nil, reasoning_effort: nil, now: Time.now, memory_context: nil, plugin_context: nil)
-      parts = [base_prompt, config_agents_prompt]
-      parts << memory_context unless memory_context.to_s.empty?
-      parts << persona_prompt(workspace_root, model: model, reasoning_effort: reasoning_effort, now: now) if include_workspace_personality
-      parts << plugin_context unless plugin_context.to_s.empty? || !include_workspace_personality
-      parts << skills_prompt
-      parts << workspace_agents_prompt(workspace_root)
-      parts
+      prompt_sections(workspace_root: workspace_root, include_workspace_personality: include_workspace_personality, model: model, reasoning_effort: reasoning_effort, now: now, memory_context: memory_context, plugin_context: plugin_context).map { |section| section[:content] }
+    end
+
+    def prompt_sections(workspace_root: Dir.pwd, include_workspace_personality: true, model: nil, reasoning_effort: nil, now: Time.now, memory_context: nil, plugin_context: nil)
+      sections = [prompt_section("Built-in system prompt", base_prompt)]
+      sections << prompt_section(config_agents_prompt_label, config_agents_prompt, source: config_agents_prompt_source)
+      sections << prompt_section("Memory context", memory_context) unless memory_context.to_s.empty?
+      if include_workspace_personality
+        sections << prompt_section("Persona", persona_prompt(workspace_root, model: model, reasoning_effort: reasoning_effort, now: now))
+        sections << prompt_section("Plugin context", plugin_context) unless plugin_context.to_s.empty?
+      end
+      sections << prompt_section("Configured skills", skills_prompt, source: ConfigFiles.skills.empty? ? nil : File.join(ConfigFiles.config_dir, "skills"))
+      sections << prompt_section(workspace_agents_context_label(workspace_root), workspace_agents_context(workspace_root), source: ConfigFiles.workspace_agents_file?(workspace_root) ? ConfigFiles.workspace_agents_path(workspace_root) : nil)
+      sections.compact
     end
 
     def base_prompt
       <<~PROMPT.strip
         You are Kward, a concise practical CLI coding agent. You are allowed to use the tools. Help users understand and modify software projects. Inspect files before changing them, make the smallest correct change, preserve existing style, and summarize what changed. Be honest about limitations.
+
+        For web research, use web_search to discover sources, then fetch_content for important human-readable pages before relying on them. Use fetch_raw for machine-readable resources such as JSON, YAML, XML, RSS, OpenAPI specs, and plain text. Prefer official or primary sources when practical, and cite or mention the URLs you relied on.
       PROMPT
     end
 
@@ -31,14 +42,59 @@ module Kward
       ConfigFiles.agents_prompt
     end
 
+    def config_agents_prompt_label
+      return "Config principles" if File.exist?(ConfigFiles.config_principles_path)
+      return "Config AGENTS.md alias" if File.exist?(ConfigFiles.config_agents_path)
+
+      "Config principles"
+    end
+
+    def config_agents_prompt_source
+      return ConfigFiles.config_principles_path if File.exist?(ConfigFiles.config_principles_path)
+      return ConfigFiles.config_agents_path if File.exist?(ConfigFiles.config_agents_path)
+
+      nil
+    end
+
     def persona_prompt(workspace_root = Dir.pwd, model: nil, reasoning_effort: nil, now: Time.now)
       ConfigFiles.persona_prompt(workspace_root, model: model, reasoning_effort: reasoning_effort, now: now)
     end
 
+    def workspace_agents_context(workspace_root = Dir.pwd)
+      if ConfigFiles.enforce_workspace_agents_file?
+        ConfigFiles.workspace_agents_prompt(workspace_root)
+      else
+        workspace_agents_hint(workspace_root)
+      end
+    end
+
     def workspace_agents_prompt(workspace_root = Dir.pwd)
       ConfigFiles.workspace_agents_prompt(workspace_root)
     end
 
+    def workspace_agents_hint(workspace_root = Dir.pwd)
+      return nil unless ConfigFiles.workspace_agents_file?(workspace_root)
+
+      path = ConfigFiles.workspace_agents_path(workspace_root)
+      <<~PROMPT.strip
+        Workspace guidance is available in AGENTS.md at the workspace root: #{path}
+        For tasks involving this repository, read it before analyzing or modifying project files, and follow it when it does not conflict with higher-priority instructions or the user's request.
+      PROMPT
+    end
+
+    def workspace_agents_context_label(workspace_root = Dir.pwd)
+      return "Workspace AGENTS.md" unless ConfigFiles.workspace_agents_file?(workspace_root)
+      return "Workspace AGENTS.md" if ConfigFiles.enforce_workspace_agents_file?
+
+      "Workspace AGENTS.md hint"
+    end
+
+    def prompt_section(label, content, source: nil)
+      return nil if content.to_s.empty?
+
+      { label: label, content: content, source: source }
+    end
+
     def skills_prompt
       skills = ConfigFiles.skills
       return nil if skills.empty?

data/lib/kward/question_contract.rb

@@ -0,0 +1,66 @@
+require_relative "message_access"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Validates and normalizes structured clarification questions shared by CLI
+  # tools and RPC prompt bridging.
+  module QuestionContract
+    MIN_QUESTIONS = 1
+    MAX_QUESTIONS = 4
+    MIN_OPTIONS = 2
+    MAX_OPTIONS = 4
+
+    module_function
+
+    def normalize_questions(questions)
+      raise ArgumentError, "questions must be an array" unless questions.is_a?(Array)
+      unless questions.length.between?(MIN_QUESTIONS, MAX_QUESTIONS)
+        raise ArgumentError, "ui/question requires 1-4 questions"
+      end
+
+      questions.map.with_index(1) { |question, index| normalize_question(question, index) }
+    end
+
+    def normalize_question(question, index)
+      raise ArgumentError, "question #{index} must be an object" unless question.is_a?(Hash)
+      raise ArgumentError, "question #{index} multiSelect is unsupported" if has_key?(question, :multiSelect)
+
+      text = value(question, :question).to_s.strip
+      header = value(question, :header).to_s.strip
+      raise ArgumentError, "question #{index} requires question and header" if text.empty? || header.empty?
+
+      options = value(question, :options)
+      raise ArgumentError, "question #{index} options must be an array" unless options.is_a?(Array)
+      unless options.length.between?(MIN_OPTIONS, MAX_OPTIONS)
+        raise ArgumentError, "question #{index} requires 2-4 options"
+      end
+
+      {
+        question: text,
+        header: header,
+        options: options.map.with_index(1) { |option, option_index| normalize_option(option, index, option_index) }
+      }
+    end
+
+    def normalize_option(option, question_index, option_index)
+      raise ArgumentError, "question #{question_index} option #{option_index} must be an object" unless option.is_a?(Hash)
+      raise ArgumentError, "question #{question_index} preview is unsupported" if has_key?(option, :preview)
+
+      label = value(option, :label).to_s.strip
+      description = value(option, :description).to_s.strip
+      if label.empty? || description.empty?
+        raise ArgumentError, "question #{question_index} option #{option_index} requires label and description"
+      end
+
+      { label: label, description: description }
+    end
+
+    def value(object, key)
+      MessageAccess.value(object, key)
+    end
+
+    def has_key?(object, key)
+      object.key?(key) || object.key?(key.to_s)
+    end
+  end
+end

data/lib/kward/resources/avatar_kward_logo.rb

@@ -1,7 +1,9 @@
 # Generated from avatar_kward_32x32.png as RGB terminal cells.
 # The interactive banner uses this data instead of decoding a PNG at runtime.
 module Kward
+  # Static avatar logo data used by generated resources.
   module Resources
+    # Static avatar logo data used by generated resources.
     module AvatarKwardLogo
       PIXELS = [
         [nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil],

data/lib/kward/resources/pixel_logo.rb

@@ -1,6 +1,8 @@
 require "zlib"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Pixel-art logo data and rendering helpers.
   module PixelLogo
     PNG_SIGNATURE = "\x89PNG\r\n\x1a\n".b.freeze
     TRANSPARENT_ALPHA = 128

data/lib/kward/rpc/attachment_normalizer.rb

@@ -0,0 +1,60 @@
+require "base64"
+require_relative "../tools/tool_call"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # JSON-RPC backend namespace used by UI clients.
+  module RPC
+    # Validates and normalizes RPC image attachments.
+    class AttachmentNormalizer
+      IMAGE_MIME_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"].freeze
+      MAX_BYTES = 10 * 1024 * 1024
+
+      def initialize(max_bytes: MAX_BYTES, mime_types: IMAGE_MIME_TYPES)
+        @max_bytes = max_bytes
+        @mime_types = mime_types
+      end
+
+      def normalize(attachments)
+        return [] if attachments.nil?
+        raise ArgumentError, "attachments must be an array" unless attachments.is_a?(Array)
+
+        attachments.map { |attachment| normalize_attachment(attachment) }
+      end
+
+      private
+
+      def normalize_attachment(attachment)
+        raise ArgumentError, "attachment must be an object" unless attachment.is_a?(Hash)
+
+        type = ToolCall.value(attachment, :type).to_s
+        raise ArgumentError, "Unsupported attachment type: #{type.empty? ? "unknown" : type}" unless type == "image"
+
+        mime_type = normalize_mime_type(ToolCall.value(attachment, :mimeType) || ToolCall.value(attachment, :mime_type) || ToolCall.value(attachment, :media_type))
+        raise ArgumentError, "Unsupported image MIME type: #{mime_type.empty? ? "unknown" : mime_type}" unless @mime_types.include?(mime_type)
+
+        data = ToolCall.value(attachment, :data).to_s
+        raise ArgumentError, "Image attachment data must be valid base64" if data.empty?
+        raise ArgumentError, "Image attachment data must be raw base64" if data.start_with?("data:")
+        declared_size = ToolCall.value(attachment, :sizeBytes) || ToolCall.value(attachment, :size_bytes)
+        raise ArgumentError, "Image attachment is too large" if declared_size && declared_size.to_i > @max_bytes
+
+        decoded_size = Base64.strict_decode64(data).bytesize
+        raise ArgumentError, "Image attachment is too large" if decoded_size > @max_bytes
+
+        result = { type: "image", data: data, mimeType: mime_type }
+        name = ToolCall.value(attachment, :name)
+        result[:alt] = name.to_s unless name.to_s.empty?
+        result
+      rescue ArgumentError => e
+        raise e if e.message.start_with?("Unsupported", "Image attachment", "attachment")
+
+        raise ArgumentError, "Image attachment data must be valid base64"
+      end
+
+      def normalize_mime_type(mime_type)
+        mime_type.to_s.downcase
+      end
+    end
+  end
+end

data/lib/kward/rpc/auth_manager.rb

@@ -1,19 +1,24 @@
 require "securerandom"
 require "thread"
+require_relative "../auth/anthropic_oauth"
 require_relative "../auth/github_oauth"
 require_relative "../auth/openai_oauth"
 require_relative "../model/client"
 require_relative "config_manager"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # JSON-RPC backend namespace used by UI clients.
   module RPC
+    # RPC authentication manager for provider status, login, and logout requests.
     class AuthManager
-      Login = Struct.new(:id, :oauth, :pkce, :state, :server, :redirect_uri, :status, :error, :thread, keyword_init: true)
+      Login = Struct.new(:id, :provider_id, :oauth, :pkce, :state, :server, :redirect_uri, :status, :error, :thread, keyword_init: true)
 
-      def initialize(server:, oauth_factory: -> { OpenAIOAuth.new }, github_oauth_factory: -> { GithubOAuth.new }, config_manager: ConfigManager.new)
+      def initialize(server:, oauth_factory: -> { OpenAIOAuth.new }, github_oauth_factory: -> { GithubOAuth.new }, anthropic_oauth_factory: -> { AnthropicOAuth.new }, config_manager: ConfigManager.new)
         @server = server
         @oauth_factory = oauth_factory
         @github_oauth_factory = github_oauth_factory
+        @anthropic_oauth_factory = anthropic_oauth_factory
         @config_manager = config_manager
         @logins = {}
         @mutex = Mutex.new
@@ -27,6 +32,7 @@ module Kward
           openaiAccountId: oauth.respond_to?(:account_id) ? oauth.account_id : nil,
           openrouterApiKey: !ENV["OPENROUTER_API_KEY"].to_s.empty? || !config["openrouter_api_key"].to_s.empty?,
           openaiAccessToken: !ENV["OPENAI_ACCESS_TOKEN"].to_s.empty?,
+          anthropicOAuth: @anthropic_oauth_factory.call.logged_in?,
           githubOAuth: @github_oauth_factory.call.logged_in?
         }
       rescue StandardError => e
@@ -34,7 +40,7 @@ module Kward
       end
 
       def providers
-        { providers: [openai_provider, openrouter_provider, github_provider] }
+        { providers: [openai_provider, anthropic_provider, openrouter_provider, github_provider] }
       end
 
       def login_with_api_key(provider_id:, api_key:)
@@ -49,6 +55,9 @@ module Kward
         when "openai"
           logout_openai
           { providerId: provider_id, message: "Logged out of OpenAI." }
+        when "anthropic"
+          logout_anthropic
+          { providerId: provider_id, message: "Logged out of Anthropic." }
         when "openrouter"
           @config_manager.delete_key("openrouter_api_key")
           { providerId: provider_id, message: "Logged out of OpenRouter." }
@@ -61,7 +70,9 @@ module Kward
         provider_id = provider_id.to_s
         case provider_id
         when "openai"
-          start_openai_login(timeout_seconds: timeout_seconds)
+          start_oauth_login(provider_id: "openai", oauth: @oauth_factory.call, timeout_seconds: timeout_seconds)
+        when "anthropic"
+          start_oauth_login(provider_id: "anthropic", oauth: @anthropic_oauth_factory.call, timeout_seconds: timeout_seconds)
         when "github"
           raise "GitHub OAuth is supported in the CLI with `ruby lib/main.rb login github`, but RPC browser login is not implemented yet."
         else
@@ -70,7 +81,10 @@ module Kward
       end
 
       def start_openai_login(timeout_seconds: 120)
-        oauth = @oauth_factory.call
+        start_oauth_login(provider_id: "openai", oauth: @oauth_factory.call, timeout_seconds: timeout_seconds)
+      end
+
+      def start_oauth_login(provider_id:, oauth:, timeout_seconds: 120)
         flow = oauth.start_login_flow
         pkce = flow.fetch(:pkce)
         state = flow.fetch(:state)
@@ -79,6 +93,7 @@ module Kward
         url = flow.fetch(:authorization_url)
         login = Login.new(
           id: SecureRandom.uuid,
+          provider_id: provider_id,
           oauth: oauth,
           pkce: pkce,
           state: state,
@@ -88,7 +103,7 @@ module Kward
         )
         @mutex.synchronize { @logins[login.id] = login }
         login.thread = Thread.new { wait_for_callback(login, timeout_seconds: timeout_seconds.to_i <= 0 ? 120 : timeout_seconds.to_i) }
-        { providerId: "openai", loginId: login.id, authorizationUrl: url, redirectUri: redirect_uri, status: login.status }
+        { providerId: provider_id, loginId: login.id, authorizationUrl: url, redirectUri: redirect_uri, status: login.status }
       end
 
       def submit_openai_code(login_id:, code:)
@@ -146,6 +161,34 @@ module Kward
         }.compact
       end
 
+      def anthropic_provider
+        oauth = @anthropic_oauth_factory.call
+        stored_configured = oauth.logged_in?
+        provider = {
+          id: "anthropic",
+          name: "Anthropic",
+          authType: "oauth",
+          configured: stored_configured,
+          storedCredentialType: "oauth",
+          canLogout: stored_configured,
+          usesCallbackServer: true
+        }
+        provider[:source] = "stored" if provider[:configured]
+        provider[:label] = provider[:configured] ? "Signed in" : "Not signed in"
+        provider
+      rescue StandardError
+        {
+          id: "anthropic",
+          name: "Anthropic",
+          authType: "oauth",
+          configured: false,
+          label: "Not signed in",
+          storedCredentialType: "oauth",
+          canLogout: false,
+          usesCallbackServer: true
+        }
+      end
+
       def openrouter_provider
         config = stored_config
         env_configured = !ENV["OPENROUTER_API_KEY"].to_s.empty?
@@ -200,6 +243,7 @@ module Kward
         case provider_id
         when "openrouter" then "OpenRouter"
         when "openai" then "OpenAI"
+        when "anthropic" then "Anthropic"
         when "github" then "GitHub"
         else provider_id
         end
@@ -211,6 +255,12 @@ module Kward
         File.delete(path) if path && File.exist?(path)
       end
 
+      def logout_anthropic
+        oauth = @anthropic_oauth_factory.call
+        path = oauth.auth_path if oauth.respond_to?(:auth_path)
+        File.delete(path) if path && File.exist?(path)
+      end
+
       def wait_for_callback(login, timeout_seconds:)
         code = login.oauth.wait_for_login_callback(login.server, expected_state: login.state, timeout_seconds: timeout_seconds)
         complete_login(login, code) unless code.to_s.empty?
@@ -239,7 +289,7 @@ module Kward
 
       def login_payload(login)
         {
-          providerId: "openai",
+          providerId: provider_id_for_login(login),
           loginId: login.id,
           status: login.status,
           redirectUri: login.redirect_uri,
@@ -248,16 +298,20 @@ module Kward
         }.compact
       end
 
+      def provider_id_for_login(login)
+        login.provider_id || "openai"
+      end
+
       def login_status_message(status)
         case status
         when "completed"
-          "Logged in to OpenAI."
+          "OAuth login completed."
         when "failed"
-          "OpenAI login failed."
+          "OAuth login failed."
         when "cancelled"
-          "OpenAI login cancelled."
+          "OAuth login cancelled."
         else
-          "OpenAI login pending."
+          "OAuth login pending."
         end
       end
     end

data/lib/kward/rpc/config_manager.rb

@@ -3,8 +3,11 @@ require_relative "../config_files"
 require_relative "../model/model_info"
 require_relative "redactor"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # JSON-RPC backend namespace used by UI clients.
   module RPC
+    # RPC configuration manager for reading and updating user config.
     class ConfigManager
       def initialize(config_path: OpenAIOAuth.default_config_path)
         @config_path = File.expand_path(config_path)
@@ -48,6 +51,14 @@ module Kward
         ConfigFiles.delete_config_key(key, @config_path)
       end
 
+      def workspace_guardrails_enabled?
+        ConfigFiles.workspace_guardrails_enabled?(read(redacted: false))
+      end
+
+      def session_auto_resume_enabled?
+        ConfigFiles.session_auto_resume_enabled?(read(redacted: false))
+      end
+
       private
 
       def load_config

data/lib/kward/rpc/prompt_bridge.rb

@@ -1,14 +1,13 @@
 require "securerandom"
 require_relative "../message_access"
+require_relative "../question_contract"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # JSON-RPC backend namespace used by UI clients.
   module RPC
+    # RPC prompt bridge for structured user questions.
     class PromptBridge
-      MIN_QUESTIONS = 1
-      MAX_QUESTIONS = 4
-      MIN_OPTIONS = 2
-      MAX_OPTIONS = 4
-
       def initialize(server:, session_id:)
         @server = server
         @session_id = session_id
@@ -77,27 +76,7 @@ module Kward
       end
 
       def validate_questions(questions)
-        raise ArgumentError, "questions must be an array" unless questions.is_a?(Array)
-        unless questions.length.between?(MIN_QUESTIONS, MAX_QUESTIONS)
-          raise ArgumentError, "ui/question requires 1-4 questions"
-        end
-
-        questions.each_with_index do |question, index|
-          validate_question(question, index)
-        end
-        questions
-      end
-
-      def validate_question(question, index)
-        raise ArgumentError, "question #{index + 1} must be an object" unless question.is_a?(Hash)
-
-        options = MessageAccess.value(question, :options)
-        raise ArgumentError, "question #{index + 1} options must be an array" unless options.is_a?(Array)
-        unless options.length.between?(MIN_OPTIONS, MAX_OPTIONS)
-          raise ArgumentError, "question #{index + 1} requires 2-4 options"
-        end
-        raise ArgumentError, "question #{index + 1} multiSelect is unsupported" if MessageAccess.value(question, :multiSelect) == true
-        raise ArgumentError, "question #{index + 1} preview is unsupported" if options.any? { |option| option.is_a?(Hash) && MessageAccess.value(option, :preview) }
+        QuestionContract.normalize_questions(questions)
       end
     end
   end

data/lib/kward/rpc/redactor.rb

@@ -1,5 +1,8 @@
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # JSON-RPC backend namespace used by UI clients.
   module RPC
+    # Redacts sensitive configuration values before RPC responses.
     module Redactor
       SECRET_KEYS = /(?:token|secret|api[_-]?key|authorization|password|credential)/i
 

data/lib/kward/rpc/runtime_payloads.rb

@@ -1,5 +1,8 @@
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # JSON-RPC backend namespace used by UI clients.
   module RPC
+    # Builders for Tauren-compatible runtime state payloads.
     module RuntimePayloads
       module_function
 
@@ -46,7 +49,7 @@ module Kward
           toolCalls: counts[:toolCalls],
           toolResults: counts[:toolResults],
           totalMessages: counts[:totalMessages],
-          usingSubscription: model[:provider] == "Codex",
+          usingSubscription: ["Codex", "Anthropic"].include?(model[:provider]),
           autoCompactionEnabled: compaction_enabled,
           autoCompactionReserveTokens: auto_compaction_reserve_tokens,
           contextUsage: context_usage