kward 0.78.0 → 0.80.0

data/lib/kward/skills/capture.rb

@@ -0,0 +1,144 @@
+require "fileutils"
+require "json"
+require "tempfile"
+require "yaml"
+require_relative "../compaction/token_estimator"
+require_relative "../config_files"
+require_relative "../message_access"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Skills
+    # Generates and persists reviewed personal skills from saved session branches.
+    class Capture
+      Draft = Struct.new(:content, :source_path, :name, :description, keyword_init: true)
+
+      class Error < StandardError; end
+      class SourceTooLargeError < Error; end
+      class InvalidDraftError < Error; end
+      class ConflictError < Error; end
+
+      OUTPUT_TOKEN_RESERVE = 4_096
+      PROMPT_TOKEN_RESERVE = 1_024
+      NAME_PATTERN = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+
+      def initialize(session_store:, client:, config_dir: ConfigFiles.config_dir, token_estimator: Compaction::TokenEstimator.new)
+        @session_store = session_store
+        @client = client
+        @config_dir = config_dir
+        @token_estimator = token_estimator
+      end
+
+      def generate(session_path, cancellation: nil)
+        ensure_personal_session_path!(session_path)
+        source = @session_store.capture_branch(session_path)
+        raise Error, "Session has no active branch to capture" if source[:entries].empty?
+
+        source_json = JSON.pretty_generate(source)
+        ensure_source_fits!(source_json)
+        response = @client.chat(draft_messages(source_json), tools: [], cancellation: cancellation)
+        draft(source_path: source[:path], content: MessageAccess.content(response).to_s)
+      end
+
+      def save(content, overwrite: false)
+        reviewed_draft = draft(content: content)
+        path = skill_path(reviewed_draft.name)
+        if File.exist?(path) && !overwrite
+          raise ConflictError, "A personal skill named #{reviewed_draft.name.inspect} already exists"
+        end
+
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        write_atomically(path, reviewed_draft.content)
+        reviewed_draft
+      end
+
+      def skill_path(name)
+        File.join(@config_dir, "skills", name.to_s, "SKILL.md")
+      end
+
+      private
+
+      def ensure_personal_session_path!(session_path)
+        sessions_root = File.realpath(File.join(@config_dir, "sessions"))
+        source_path = File.realpath(session_path)
+        return if source_path.start_with?("#{sessions_root}#{File::SEPARATOR}")
+
+        raise Error, "Skill capture source must be a persisted Kward session"
+      rescue Errno::ENOENT
+        raise Error, "Skill capture source must be a persisted Kward session"
+      end
+
+      def ensure_source_fits!(source_json)
+        context_window = @client.current_context_window
+        return unless context_window
+
+        available_tokens = context_window.to_i - OUTPUT_TOKEN_RESERVE - PROMPT_TOKEN_RESERVE
+        source_tokens = @token_estimator.estimate_tokens(source_json)
+        return if source_tokens <= available_tokens
+
+        raise SourceTooLargeError,
+          "Selected session needs about #{source_tokens} tokens, but only #{[available_tokens, 0].max} are available for capture"
+      end
+
+      def draft_messages(source_json)
+        [
+          {
+            role: "system",
+            content: <<~INSTRUCTIONS
+              Create one reusable Kward Agent Skill from the saved session supplied by the user.
+              Return only a complete SKILL.md document. Include YAML frontmatter with a lowercase
+              hyphenated `name` and a concise `description`, followed by practical reusable
+              instructions. Derive guidance from demonstrated workflow, commands, and conventions;
+              omit credentials, private values, and project-specific incidental details. Do not
+              claim the skill grants permissions or tool access.
+            INSTRUCTIONS
+          },
+          {
+            role: "user",
+            content: "Saved session active branch (complete persisted records):\n\n#{source_json}"
+          }
+        ]
+      end
+
+      def draft(source_path: nil, content:)
+        metadata, body = parse_skill(content)
+        name = metadata.fetch("name", "").to_s.strip
+        description = metadata.fetch("description", "").to_s.strip
+        raise InvalidDraftError, "Skill frontmatter must include a name" if name.empty?
+        raise InvalidDraftError, "Skill name must use lowercase letters, digits, and hyphens" unless NAME_PATTERN.match?(name)
+        raise InvalidDraftError, "Skill frontmatter must include a description" if description.empty?
+        raise InvalidDraftError, "Skill description exceeds 1024 characters" if description.length > 1024
+        raise InvalidDraftError, "Skill instructions must not be empty" if body.strip.empty?
+
+        Draft.new(content: normalize_content(content), source_path: source_path, name: name, description: description)
+      end
+
+      def parse_skill(content)
+        match = content.to_s.match(/\A---\r?\n(.*?)\r?\n---\r?\n(.*)\z/m)
+        raise InvalidDraftError, "Skill must begin with YAML frontmatter" unless match
+
+        metadata = YAML.safe_load(match[1], permitted_classes: [], aliases: false)
+        raise InvalidDraftError, "Skill frontmatter must be a mapping" unless metadata.is_a?(Hash)
+
+        [metadata.transform_keys(&:to_s), match[2]]
+      rescue Psych::SyntaxError => error
+        raise InvalidDraftError, "Invalid skill frontmatter: #{error.message}"
+      end
+
+      def normalize_content(content)
+        "#{content.to_s.rstrip}\n"
+      end
+
+      def write_atomically(path, content)
+        Tempfile.create(["SKILL", ".tmp"], File.dirname(path)) do |file|
+          file.write(content)
+          file.flush
+          file.fsync
+          File.chmod(0o600, file.path)
+          File.rename(file.path, path)
+        end
+        File.chmod(0o600, path)
+      end
+    end
+  end
+end

data/lib/kward/tab_driver.rb

@@ -3,11 +3,12 @@ module Kward
   # Adapts a session-backed agent to the tab runtime interface. Plugin tab
   # drivers implement the same small surface without becoming Kward sessions.
   class SessionTabDriver
-    attr_reader :session, :agent
+    attr_reader :session, :agent, :worktree
 
-    def initialize(session:, agent:)
+    def initialize(session:, agent:, worktree: nil)
       @session = session
       @agent = agent
+      @worktree = worktree
     end
 
     def messages
@@ -26,7 +27,9 @@ module Kward
     end
 
     def descriptor
-      { "kind" => "session", "session_path" => session.path }
+      descriptor = { "kind" => "session", "session_path" => session.path }
+      descriptor["worktree"] = worktree.descriptor if worktree
+      descriptor
     end
 
     def session?

data/lib/kward/tools/git_commit.rb

@@ -0,0 +1,39 @@
+require_relative "base"
+
+# Namespace for model-callable tool wrappers.
+module Kward
+  module Tools
+    # Tool wrapper for the trusted host-side Git commit operation.
+    class GitCommit < Base
+      def initialize(committer:)
+        @committer = committer
+        super(
+          "git_commit",
+          "Stage and commit changes in the active worktree. Omit paths to include all current changes.",
+          properties: {
+            message: { type: "string", description: "Commit message." },
+            paths: { type: "array", items: { type: "string" }, description: "Optional workspace-relative paths to include." }
+          },
+          required: ["message"]
+        )
+      end
+
+      def call(args, _conversation, cancellation: nil)
+        cancellation&.raise_if_cancelled!
+        message = argument(args, :message, "").to_s
+        paths = argument(args, :paths, nil)
+        return "Error: commit message is required" if message.strip.empty?
+        return "Error: paths must be an array" unless paths.nil? || paths.is_a?(Array)
+        return "Error: paths must contain strings" if paths && paths.any? { |path| !path.is_a?(String) }
+
+        paths = nil if paths&.empty?
+        result = @committer.call(message: message, paths: paths)
+        output = result[:output].to_s.strip
+        return "Git commit succeeded\n#{output}" if result[:success]
+
+        failure = output.empty? ? "Git commit failed." : "Git commit failed.\n#{output}"
+        "Error: #{failure}"
+      end
+    end
+  end
+end

data/lib/kward/tools/registry.rb

@@ -8,6 +8,7 @@ require_relative "context_for_task"
 require_relative "edit_file"
 require_relative "fetch_content"
 require_relative "fetch_raw"
+require_relative "git_commit"
 require_relative "list_directory"
 require_relative "mcp_tool"
 require_relative "read_file"
@@ -49,6 +50,19 @@ module Kward
   # explicit tool errors.
   # @api public
   class ToolRegistry
+    CORE_TOOL_NAMES = %w[
+      list_directory
+      read_file
+      write_file
+      edit_file
+      run_shell_command
+      code_search
+      summarize_file_structure
+      context_for_task
+      context_budget_stats
+      retrieve_tool_output
+    ].freeze
+
     # Tool schemas advertised to the model for the current frontend and config.
     #
     # @return [Array<Hash>] tool schemas currently advertised to the model
@@ -65,7 +79,7 @@ module Kward
     # @param web_search_enabled [Boolean, nil] override for web search exposure
     # @param skills [Array<ConfigFiles::Skill>, nil] override discovered skills
     # @param ask_user_question_enabled [Boolean, nil] override question exposure
-    def initialize(workspace: Workspace.new, prompt: nil, web_search: WebSearch.new, web_fetch: WebFetch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil, allowed_tool_names: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, tool_approval: nil, approval_for_allowed_tools: false, permission_policy: nil, hook_manager: nil, hook_context: nil)
+    def initialize(workspace: Workspace.new, prompt: nil, web_search: WebSearch.new, web_fetch: WebFetch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil, allowed_tool_names: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, tool_approval: nil, approval_for_allowed_tools: false, permission_policy: nil, hook_manager: nil, hook_context: nil, git_committer: nil)
       @workspace = workspace
       @prompt = prompt
       @web_search = web_search
@@ -83,6 +97,7 @@ module Kward
       @permission_policy = permission_policy || Permissions::Policy.from_config(ConfigFiles.read_config)
       @hook_manager = hook_manager
       @hook_context = hook_context
+      @git_committer = git_committer
       @mcp_clients = if mcp_clients
                        mcp_clients
                      elsif @allowed_tool_names
@@ -462,13 +477,16 @@ module Kward
     def build_tools
       tools = all_tools
       tools = tools.select { |tool| @allowed_tool_names.include?(tool.name) } if @allowed_tool_names
-      tools.to_h { |tool| [tool.name, tool] }
+      tools.each_with_object({}) do |tool, result|
+        raise ArgumentError, "Duplicate tool name: #{tool.name}" if result.key?(tool.name)
+
+        result[tool.name] = tool
+      end
     end
 
     def build_schema_tools
-      tools = @tools.values_at(
-        "list_directory", "read_file", "write_file", "edit_file", "run_shell_command", "code_search", "summarize_file_structure", "context_for_task", "context_budget_stats", "retrieve_tool_output"
-      )
+      tools = @tools.values_at(*CORE_TOOL_NAMES)
+      tools << @tools["git_commit"] if @tools["git_commit"]
       tools.concat(@tools.values_at("web_search", "fetch_content", "fetch_raw")) if web_search_available?
       tools.concat(@tools.values.select { |tool| tool.is_a?(Tools::MCPTool) })
       tools << @tools["read_skill"] if skills_available?
@@ -477,7 +495,9 @@ module Kward
     end
 
     def all_tools
-      core_tools + [
+      tools = core_tools
+      tools << Tools::GitCommit.new(committer: @git_committer) if @git_committer
+      tools + [
         Tools::WebSearch.new(web_search: @web_search),
         Tools::FetchContent.new(web_fetch: @web_fetch),
         Tools::FetchRaw.new(web_fetch: @web_fetch),

data/lib/kward/tools/tool_call.rb

@@ -24,6 +24,7 @@ module Kward
       "web_search" => "web_search",
       "fetch_content" => "fetch_content",
       "fetch_raw" => "fetch_raw",
+      "git_commit" => "git_commit",
       "read_skill" => "read_skill",
       "ask_user_question" => "ask_user_question"
     }.freeze

data/lib/kward/transport/gateway.rb

@@ -0,0 +1,253 @@
+require "base64"
+require "digest"
+require "thread"
+require_relative "../deep_copy"
+require_relative "store"
+
+module Kward
+  module Transport
+    # Adapts the existing session manager to the transport host contract.
+    #
+    # The adapter deliberately uses the manager's public session and turn
+    # methods. It can be replaced by a frontend-neutral runtime gateway later
+    # without changing transport plugins.
+    class Gateway
+      POLL_INTERVAL = 0.05
+      TERMINAL_STATUSES = %w[completed canceled failed].freeze
+
+      def initialize(session_manager:, transport_id:, storage: nil, poll_interval: POLL_INTERVAL)
+        @session_manager = session_manager
+        @transport_id = transport_id.to_s
+        @storage = storage || Store.new(@transport_id)
+        @poll_interval = poll_interval
+        @subscriptions = []
+        @interaction_subscribers = []
+        @mutex = Mutex.new
+        @session_manager.subscribe_events { |method, payload| handle_runtime_event(method, payload) } if @session_manager.respond_to?(:subscribe_events)
+      end
+
+      def resolve_transport_session(transport_id:, conversation:, actor:, workspace_root: nil, name: nil, execution_profile: nil)
+        raise ArgumentError, "transport id does not match gateway" unless transport_id.to_s == @transport_id
+        if conversation.respond_to?(:transport_id) && conversation.transport_id.to_s != @transport_id
+          raise ArgumentError, "conversation transport does not match gateway"
+        end
+
+        binding_key = binding_key_for(conversation)
+        binding = @storage.get(binding_key)
+        session = if binding
+                     resume_bound_session(binding, execution_profile: execution_profile)
+                   else
+                     @session_manager.create_session(workspace_root: workspace_root || Dir.pwd, name: name, **execution_profile_arguments(execution_profile))
+                   end
+        persist_binding(binding_key, session)
+        session_handle(session)
+      end
+
+      def start_transport_turn(session_id:, input:, attachments: [], options: {}, streaming_behavior: nil, execution_profile: nil)
+        payload = @session_manager.start_turn(
+          session_id: session_id,
+          input: input,
+          attachments: normalize_attachments(attachments, execution_profile: execution_profile),
+          options: profile_options(options, execution_profile),
+          streaming_behavior: streaming_behavior,
+          execution_profile: execution_profile
+        )
+        { id: payload.fetch(:id), session_id: payload.fetch(:sessionId) }
+      end
+
+      def transport_transcript(session_id:)
+        @session_manager.transcript(session_id: session_id)
+      end
+
+      def transport_turn_events(turn_id:, after: nil)
+        payload = @session_manager.turn_events(turn_id: turn_id, after_sequence: after.to_i)
+        Array(payload[:events]).map { |event| normalize_event(event) }
+      end
+
+      def transport_turn_status(turn_id:)
+        @session_manager.turn_status(turn_id: turn_id)
+      end
+
+      def cancel_transport_turn(turn_id:)
+        @session_manager.cancel_turn(turn_id: turn_id)
+      end
+
+      def answer_transport_interaction(session_id:, request_id:, answer:)
+        if answer == true || answer == false
+          @session_manager.answer_tool_approval(
+            session_id: session_id,
+            approval_request_id: request_id,
+            approved: answer
+          )
+        else
+          answers = answer.is_a?(Array) ? answer : [{ question: request_id, answer: answer.to_s }]
+          @session_manager.answer_question(
+            session_id: session_id,
+            question_request_id: request_id,
+            answers: answers
+          )
+        end
+      end
+
+      def subscribe_transport_interactions(&block)
+        raise ArgumentError, "interaction subscription requires a block" unless block
+
+        @mutex.synchronize { @interaction_subscribers << block }
+        block
+      end
+
+      def subscribe_transport_turn(turn_id:, after: nil)
+        cursor = after.to_i
+        thread = Thread.new do
+          loop do
+            events = transport_turn_events(turn_id: turn_id, after: cursor)
+            events.each do |event|
+              cursor = event.sequence
+              yield event
+            end
+            status = transport_turn_status(turn_id: turn_id)
+            break if TERMINAL_STATUSES.include?(status[:status].to_s)
+
+            sleep @poll_interval
+          end
+        rescue StandardError
+          nil
+        end
+        @mutex.synchronize { @subscriptions << thread }
+        thread
+      end
+
+      def shutdown
+        subscriptions = @mutex.synchronize do
+          current = @subscriptions
+          @subscriptions = []
+          @interaction_subscribers = []
+          current
+        end
+        subscriptions.each(&:kill)
+        subscriptions.each(&:join)
+        nil
+      end
+
+      private
+
+      def resume_bound_session(binding, execution_profile: nil)
+        @session_manager.resume_session(
+          path: binding.fetch("path"),
+          workspace_root: binding.fetch("workspace_root"),
+          include_transcript: false,
+          **execution_profile_arguments(execution_profile)
+        )
+      rescue StandardError
+        @session_manager.create_session(workspace_root: binding.fetch("workspace_root"), **execution_profile_arguments(execution_profile))
+      end
+
+      def execution_profile_arguments(profile)
+        profile ? { execution_profile: profile } : {}
+      end
+
+      def persist_binding(key, session)
+        @storage.put(key, {
+          "path" => session.fetch(:path),
+          "workspace_root" => session.fetch(:workspaceRoot)
+        })
+      end
+
+      def session_handle(session)
+        Host::SessionHandle.new(
+          id: session.fetch(:id),
+          workspace_root: session.fetch(:workspaceRoot),
+          name: session[:name]
+        )
+      end
+
+      def binding_key_for(conversation)
+        external_id = conversation.respond_to?(:external_id) ? conversation.external_id : conversation.to_s
+        digest = Digest::SHA256.hexdigest("#{@transport_id}\0#{external_id}")
+        "binding:#{digest}"
+      end
+
+      def handle_runtime_event(method, payload)
+        request = case method
+                  when "ui/question"
+                    questions = Array(payload[:questions] || payload["questions"])
+                    Transport.interaction_request(
+                      id: payload[:questionRequestId] || payload["questionRequestId"],
+                      session_id: payload[:sessionId] || payload["sessionId"],
+                      turn_id: payload[:turnId] || payload["turnId"] || "unknown",
+                      kind: :question,
+                      prompt: questions.map { |question| question[:question] || question["question"] }.join("\\n"),
+                      choices: questions
+                    )
+                  when "tool/approvalRequested"
+                    Transport.interaction_request(
+                      id: payload[:approvalRequestId] || payload["approvalRequestId"],
+                      session_id: payload[:sessionId] || payload["sessionId"],
+                      turn_id: payload[:turnId] || payload["turnId"] || "unknown",
+                      kind: :tool_approval,
+                      prompt: "Allow #{payload[:toolName] || payload["toolName"]}?",
+                      choices: [{ id: "approve", label: "Approve" }, { id: "deny", label: "Deny" }],
+                      metadata: { tool_call_id: payload[:toolCallId] || payload["toolCallId"], args: payload[:args] || payload["args"] }
+                    )
+                  end
+        return unless request
+
+        subscribers = @mutex.synchronize { @interaction_subscribers.dup }
+        subscribers.each do |subscriber|
+          begin
+            subscriber.call(request)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      def profile_options(options, profile)
+        return options unless profile
+
+        options = options.dup
+        case profile.tool_mode
+        when :none
+          options.delete("disabledTools")
+          options.delete(:disabled_tools)
+          options["allowedTools"] = []
+        when :allowlist
+          options.delete("disabledTools")
+          options.delete(:disabled_tools)
+          options["allowedTools"] = profile.allowed_tools
+        end
+        options["approvalMode"] = "none" if profile.approval_mode == :deny
+        options["approvalMode"] = "ask" if profile.approval_mode == :ask
+        options
+      end
+
+      def normalize_attachments(attachments, execution_profile: nil)
+        if execution_profile && !execution_profile.attachments && !Array(attachments).empty?
+          raise ArgumentError, "transport execution profile does not allow attachments"
+        end
+
+        Array(attachments).map do |attachment|
+          raise ArgumentError, "transport attachment must be a Transport::Attachment" unless attachment.is_a?(Attachment)
+          raise ArgumentError, "transport attachment URLs are not supported by the session gateway" if attachment.url
+
+          {
+            type: "image",
+            data: Base64.strict_encode64(attachment.data),
+            mimeType: attachment.mime_type,
+            name: attachment.name
+          }.compact
+        end
+      end
+
+      def normalize_event(event)
+        Transport.turn_event(
+          type: event.fetch(:type),
+          session_id: event.fetch(:sessionId),
+          turn_id: event.fetch(:turnId),
+          sequence: event.fetch(:sequence),
+          payload: event.fetch(:payload, {})
+        )
+      end
+    end
+  end
+end