kward 0.79.0 → 0.80.1

data/lib/kward/transport/runtime.rb

@@ -0,0 +1,41 @@
+require "stringio"
+require_relative "../config_files"
+require_relative "../rpc/server"
+require_relative "gateway"
+require_relative "manager"
+require_relative "plugin_chat_gateway"
+
+module Kward
+  module Transport
+    # Builds the Kward runtime needed by foreground transport processes.
+    class Runtime
+      attr_reader :manager
+
+      def initialize(client:)
+        @server = RPC::Server.new(
+          input: StringIO.new,
+          output: StringIO.new,
+          error_output: $stderr,
+          client: client
+        )
+        @manager = Manager.new(
+          registry: @server.session_manager.plugin_registry,
+          gateway: lambda { |transport_id|
+            Gateway.new(session_manager: @server.session_manager, transport_id: transport_id)
+          },
+          plugin_chat_gateway: lambda { |transport_id|
+            PluginChatGateway.new(runtime: @server.plugin_chat_manager.runtime, transport_id: transport_id)
+          },
+          config_root: ConfigFiles.config_dir,
+          config_provider: ->(transport_id) { ConfigFiles.transport_config(transport_id) }
+        )
+      end
+
+      def shutdown
+        @manager.shutdown
+        @server.shutdown
+        nil
+      end
+    end
+  end
+end

data/lib/kward/transport/store.rb

@@ -0,0 +1,101 @@
+require "fileutils"
+require "json"
+require "thread"
+require "time"
+require_relative "../config_files"
+require_relative "../deep_copy"
+require_relative "../private_file"
+
+module Kward
+  module Transport
+    # Small private JSON store scoped to one transport plugin.
+    class Store
+      KEY_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9:._-]*\z/.freeze
+      DEFAULT_MAX_PROCESSED_KEYS = 10_000
+
+      attr_reader :transport_id
+
+      def initialize(transport_id, root: ConfigFiles.config_dir)
+        @transport_id = validate_key(transport_id, "transport id")
+        @path = File.join(File.expand_path(root), "transports", @transport_id, "state.json")
+        @mutex = Mutex.new
+        @values, @processed = load_state
+      end
+
+      def get(key)
+        key = validate_key(key, "storage key")
+        @mutex.synchronize { copy(@values[key]) }
+      end
+
+      def put(key, value)
+        key = validate_key(key, "storage key")
+        @mutex.synchronize do
+          @values[key] = copy(value)
+          persist
+        end
+        value
+      end
+
+      def delete(key)
+        key = validate_key(key, "storage key")
+        @mutex.synchronize do
+          present = @values.key?(key)
+          value = @values.delete(key)
+          persist if present
+          copy(value)
+        end
+      end
+
+      # Claims an external event key. Returns false when the key was already
+      # claimed, making duplicate webhook and polling deliveries harmless.
+      def claim(key, max_keys: DEFAULT_MAX_PROCESSED_KEYS)
+        key = validate_key(key, "idempotency key")
+        max_keys = Integer(max_keys)
+        raise ArgumentError, "max_keys must be positive" unless max_keys.positive?
+
+        @mutex.synchronize do
+          return false if @processed.key?(key)
+
+          @processed[key] = Time.now.utc.iso8601
+          @processed.shift while @processed.length > max_keys
+          persist
+          true
+        end
+      end
+
+      private
+
+      def load_state
+        return [{}, {}] unless File.file?(@path)
+
+        state = JSON.parse(File.read(@path))
+        values = state.fetch("values", {})
+        processed = state.fetch("processed", {})
+        unless values.is_a?(Hash) && processed.is_a?(Hash)
+          raise JSON::ParserError, "transport state must contain JSON objects"
+        end
+
+        [values, processed]
+      rescue JSON::ParserError => e
+        raise "Invalid transport state #{@path}: #{e.message}"
+      end
+
+      def persist
+        PrivateFile.write_json(@path, "values" => @values, "processed" => @processed)
+      end
+
+      def validate_key(value, name)
+        value = value.to_s
+        raise ArgumentError, "#{name} is required" unless value.match?(KEY_PATTERN)
+
+        value
+      end
+
+      def copy(value)
+        return nil if value.nil?
+
+        DeepCopy.dup(value)
+      end
+    end
+  end
+end

data/lib/kward/transport.rb

@@ -0,0 +1,204 @@
+require "logger"
+require_relative "deep_copy"
+
+# Namespace for frontend-neutral external transport contracts.
+module Kward
+  module Transport
+    STREAMING_MODES = %i[native edit aggregate none].freeze
+
+    Actor = Data.define(:id, :display_name, :metadata)
+    Attachment = Data.define(:name, :mime_type, :data, :url, :metadata)
+    ConversationKey = Data.define(:transport_id, :external_id)
+    InboundMessage = Data.define(
+      :conversation,
+      :message_id,
+      :actor,
+      :text,
+      :attachments,
+      :reply_context,
+      :idempotency_key,
+      :metadata
+    )
+    TurnEvent = Data.define(:type, :session_id, :turn_id, :sequence, :payload)
+    InteractionRequest = Data.define(
+      :id,
+      :session_id,
+      :turn_id,
+      :kind,
+      :prompt,
+      :choices,
+      :expires_at,
+      :metadata
+    )
+    Capabilities = Data.define(:inbound, :outbound, :streaming, :limits)
+    ExecutionProfile = Data.define(
+      :id,
+      :tool_mode,
+      :allowed_tools,
+      :disabled_tools,
+      :plugin_commands,
+      :approval_mode,
+      :memory,
+      :attachments,
+      :workspace_mode,
+      :prompt_context
+    )
+
+    TOOL_MODES = %i[all none allowlist].freeze
+    APPROVAL_MODES = %i[default ask deny].freeze
+    MEMORY_MODES = %i[default none].freeze
+    WORKSPACE_MODES = %i[session fixed].freeze
+
+    module_function
+
+    def actor(id:, display_name: nil, metadata: {})
+      Actor.new(
+        id: required_string(id, "actor id"),
+        display_name: optional_string(display_name),
+        metadata: frozen_copy(metadata)
+      )
+    end
+
+    def attachment(name: nil, mime_type:, data: nil, url: nil, metadata: {})
+      raise ArgumentError, "attachment requires data or url" if data.nil? && url.nil?
+      raise ArgumentError, "attachment cannot contain both data and url" unless data.nil? || url.nil?
+
+      Attachment.new(
+        name: optional_string(name),
+        mime_type: required_string(mime_type, "attachment MIME type"),
+        data: data&.dup&.freeze,
+        url: url && required_string(url, "attachment URL"),
+        metadata: frozen_copy(metadata)
+      )
+    end
+
+    def conversation_key(transport_id:, external_id:)
+      ConversationKey.new(
+        transport_id: required_string(transport_id, "transport id"),
+        external_id: required_string(external_id, "external conversation id")
+      )
+    end
+
+    def inbound_message(conversation:, message_id:, actor:, text: "", attachments: [], reply_context: {}, idempotency_key:, metadata: {})
+      unless conversation.is_a?(ConversationKey)
+        raise ArgumentError, "conversation must be a Transport::ConversationKey"
+      end
+      unless actor.is_a?(Actor)
+        raise ArgumentError, "actor must be a Transport::Actor"
+      end
+
+      InboundMessage.new(
+        conversation: conversation,
+        message_id: required_string(message_id, "message id"),
+        actor: actor,
+        text: text.to_s.freeze,
+        attachments: frozen_copy(Array(attachments)),
+        reply_context: frozen_copy(reply_context),
+        idempotency_key: required_string(idempotency_key, "idempotency key"),
+        metadata: frozen_copy(metadata)
+      )
+    end
+
+    def turn_event(type:, session_id:, turn_id:, sequence:, payload: {})
+      TurnEvent.new(
+        type: required_string(type, "turn event type"),
+        session_id: required_string(session_id, "session id"),
+        turn_id: required_string(turn_id, "turn id"),
+        sequence: Integer(sequence),
+        payload: frozen_copy(payload)
+      )
+    end
+
+    def interaction_request(id:, session_id:, turn_id:, kind:, prompt:, choices: [], expires_at: nil, metadata: {})
+      InteractionRequest.new(
+        id: required_string(id, "interaction id"),
+        session_id: required_string(session_id, "session id"),
+        turn_id: required_string(turn_id, "turn id"),
+        kind: required_string(kind, "interaction kind"),
+        prompt: required_string(prompt, "interaction prompt"),
+        choices: frozen_copy(Array(choices)),
+        expires_at: expires_at,
+        metadata: frozen_copy(metadata)
+      )
+    end
+
+    def execution_profile(
+      id:,
+      tool_mode: :all,
+      allowed_tools: nil,
+      disabled_tools: nil,
+      plugin_commands: true,
+      approval_mode: :default,
+      memory: :default,
+      attachments: true,
+      workspace_mode: :session,
+      prompt_context: nil
+    )
+      id = required_string(id, "execution profile id")
+      tool_mode = tool_mode.to_sym
+      approval_mode = approval_mode.to_sym
+      memory = memory.to_sym
+      workspace_mode = workspace_mode.to_sym
+      raise ArgumentError, "unsupported tool mode: #{tool_mode}" unless TOOL_MODES.include?(tool_mode)
+      raise ArgumentError, "unsupported approval mode: #{approval_mode}" unless APPROVAL_MODES.include?(approval_mode)
+      raise ArgumentError, "unsupported memory mode: #{memory}" unless MEMORY_MODES.include?(memory)
+      raise ArgumentError, "unsupported workspace mode: #{workspace_mode}" unless WORKSPACE_MODES.include?(workspace_mode)
+      raise ArgumentError, "allowlist tool mode requires allowed_tools" if tool_mode == :allowlist && Array(allowed_tools).empty?
+      raise ArgumentError, "none tool mode cannot define allowed_tools" if tool_mode == :none && allowed_tools
+      raise ArgumentError, "allowed_tools and disabled_tools cannot both be set" if allowed_tools && disabled_tools
+
+      ExecutionProfile.new(
+        id: id,
+        tool_mode: tool_mode,
+        allowed_tools: frozen_symbols(allowed_tools),
+        disabled_tools: frozen_symbols(disabled_tools),
+        plugin_commands: !!plugin_commands,
+        approval_mode: approval_mode,
+        memory: memory,
+        attachments: !!attachments,
+        workspace_mode: workspace_mode,
+        prompt_context: prompt_context.nil? ? nil : prompt_context.to_s.freeze
+      )
+    end
+
+    def capabilities(inbound: [], outbound: [], streaming: :none, limits: {})
+      streaming = streaming.to_sym
+      raise ArgumentError, "unsupported streaming mode: #{streaming}" unless STREAMING_MODES.include?(streaming)
+
+      Capabilities.new(
+        inbound: frozen_symbols(inbound),
+        outbound: frozen_symbols(outbound),
+        streaming: streaming,
+        limits: frozen_copy(limits)
+      )
+    end
+
+    def required_string(value, name)
+      value = value.to_s
+      raise ArgumentError, "#{name} is required" if value.empty?
+
+      value.freeze
+    end
+    private_class_method :required_string
+
+    def optional_string(value)
+      value.nil? ? nil : value.to_s.freeze
+    end
+    private_class_method :optional_string
+
+    def frozen_symbols(values)
+      Array(values).map { |value| value.to_sym }.uniq.freeze
+    end
+    private_class_method :frozen_symbols
+
+    def frozen_copy(value)
+      DeepCopy.freeze(DeepCopy.dup(value))
+    end
+    private_class_method :frozen_copy
+  end
+end
+
+require_relative "transport/store"
+require_relative "transport/host"
+require_relative "transport/manager"
+require_relative "transport/gateway"

data/lib/kward/version.rb

@@ -1,5 +1,5 @@
 # Namespace for the Kward CLI agent runtime.
 module Kward
   # Current gem version.
-  VERSION = "0.79.0"
+  VERSION = "0.80.1"
 end

data/lib/kward/workspace_factory.rb

@@ -8,10 +8,27 @@ module Kward
   module WorkspaceFactory
     module_function
 
-    def build(root:, guardrails: true, config: ConfigFiles.read_config)
+    def build(root:, guardrails: true, config: ConfigFiles.read_config, strict: false)
       policy = ConfigFiles.sandbox_policy(root, config)
+      policy = strict_policy(root, policy) if strict
       runner = Sandbox::RunnerFactory.build(policy)
-      Workspace.new(root:, guardrails:, command_runner: runner)
+      if strict && !runner.capabilities.filesystem_enforced?
+        reason = runner.capabilities.reason || "filesystem enforcement is unavailable"
+        raise Sandbox::UnavailableError, "Strict workspace sandbox is unavailable: #{reason}"
+      end
+
+      Workspace.new(root:, guardrails: strict ? true : guardrails, command_runner: runner)
+    end
+
+    def strict_policy(root, configured_policy)
+      Sandbox::Policy.new(
+        mode: "workspace_write",
+        network: configured_policy.network,
+        workspace_root: root,
+        writable_roots: [],
+        protect_git_metadata: configured_policy.protect_git_metadata?
+      )
     end
+    private_class_method :strict_policy
   end
 end

data/templates/default/fulldoc/html/js/kward.js

@@ -4,6 +4,7 @@ const guideLinks = {
   'doc/usage.md': 'file.usage.html',
   'doc/configuration.md': 'file.configuration.html',
   'doc/authentication.md': 'file.authentication.html',
+  'doc/providers.md': 'file.providers.html',
   'doc/sandboxing.md': 'file.sandboxing.html',
   'doc/troubleshooting.md': 'file.troubleshooting.html',
   'doc/session-management.md': 'file.session-management.html',
@@ -19,6 +20,7 @@ const guideLinks = {
   'doc/code-search.md': 'file.code-search.html',
   'doc/context-tools.md': 'file.context-tools.html',
   'doc/rpc.md': 'file.rpc.html',
+  'doc/transports.md': 'file.transports.html',
   'doc/releasing.md': 'file.releasing.html'
 }
 

data/templates/default/kward_navigation.rb

@@ -5,10 +5,12 @@ module KwardDocsNavigationData
     [
       "Start here",
       [
+        ["Overview", "file.README.html"],
         ["Getting started", "file.getting-started.html"],
         ["Usage", "file.usage.html"],
         ["Configuration", "file.configuration.html"],
         ["Authentication", "file.authentication.html"],
+        ["Model providers", "file.providers.html"],
         ["Security and trust", "file.security.html"],
         ["Troubleshooting", "file.troubleshooting.html"]
       ]
@@ -22,8 +24,8 @@ module KwardDocsNavigationData
         ["Memory", "file.memory.html"],
         ["Personas", "file.personas.html"],
         ["Skills", "file.skills.html"],
-        ["Pan mode", "file.pan.html"],
-        ["Local models", "file.local-models.html"]
+        ["Prompt templates", "file.prompt-templates.html"],
+        ["Pan mode", "file.pan.html"]
       ]
     ],
     [
@@ -52,7 +54,10 @@ module KwardDocsNavigationData
       "Integrate",
       [
         ["MCP servers", "file.mcp.html"],
+        ["Local models", "file.local-models.html"],
         ["RPC protocol", "file.rpc.html"],
+        ["Transports", "file.transports.html"],
+        ["Telegram transport", "file.telegram.html"],
         ["Releasing", "file.releasing.html"]
       ]
     ],

data/templates/default/layout/html/setup.rb

@@ -29,6 +29,7 @@ module KwardDocsNavigation
     "doc/usage.md" => "file.usage.html",
     "doc/configuration.md" => "file.configuration.html",
     "doc/authentication.md" => "file.authentication.html",
+    "doc/providers.md" => "file.providers.html",
     "doc/permissions.md" => "file.permissions.html",
     "doc/sandboxing.md" => "file.sandboxing.html",
     "doc/troubleshooting.md" => "file.troubleshooting.html",
@@ -41,6 +42,7 @@ module KwardDocsNavigation
     "doc/memory.md" => "file.memory.html",
     "doc/personas.md" => "file.personas.html",
     "doc/skills.md" => "file.skills.html",
+    "doc/local-models.md" => "file.local-models.html",
     "doc/extensibility.md" => "file.extensibility.html",
     "doc/plugins.md" => "file.plugins.html",
     "doc/lifecycle-hooks.md" => "file.lifecycle-hooks.html",
@@ -51,6 +53,8 @@ module KwardDocsNavigation
     "doc/code-search.md" => "file.code-search.html",
     "doc/context-tools.md" => "file.context-tools.html",
     "doc/rpc.md" => "file.rpc.html",
+    "doc/transports.md" => "file.transports.html",
+    "doc/telegram.md" => "file.telegram.html",
     "doc/releasing.md" => "file.releasing.html"
   }.freeze
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kward
 version: !ruby/object:Gem::Version
-  version: 0.79.0
+  version: 0.80.1
 platform: ruby
 authors:
 - Kai Wood
@@ -146,6 +146,8 @@ files:
 - doc/permissions.md
 - doc/personas.md
 - doc/plugins.md
+- doc/prompt-templates.md
+- doc/providers.md
 - doc/releasing.md
 - doc/rpc.md
 - doc/sandboxing.md
@@ -154,17 +156,24 @@ files:
 - doc/shell.md
 - doc/skills.md
 - doc/tabs.md
+- doc/telegram.md
+- doc/transports.md
 - doc/troubleshooting.md
 - doc/usage.md
 - doc/web-search.md
 - doc/workspace-tools.md
 - examples/plugins/space_invaders.rb
+- examples/plugins/stardate_footer.rb
+- examples/plugins/telegram/plugin.rb
+- examples/plugins/telegram/telegram_api.rb
+- examples/plugins/telegram/telegram_transport.rb
 - exe/kward
 - kward.gemspec
 - lib/kward.rb
 - lib/kward/agent.rb
 - lib/kward/ansi.rb
 - lib/kward/auth/anthropic_oauth.rb
+- lib/kward/auth/api_key_store.rb
 - lib/kward/auth/file.rb
 - lib/kward/auth/github_oauth.rb
 - lib/kward/auth/oauth_helpers.rb
@@ -192,6 +201,8 @@ files:
 - lib/kward/cli/sysprompt.rb
 - lib/kward/cli/tabs.rb
 - lib/kward/cli/tool_summaries.rb
+- lib/kward/cli/transports.rb
+- lib/kward/cli/worktrees.rb
 - lib/kward/cli_transcript_formatter.rb
 - lib/kward/clipboard.rb
 - lib/kward/compaction/file_operation_tracker.rb
@@ -207,6 +218,7 @@ files:
 - lib/kward/events.rb
 - lib/kward/export_path.rb
 - lib/kward/frontmatter.rb
+- lib/kward/git_worktree_manager.rb
 - lib/kward/hooks.rb
 - lib/kward/hooks/audit_log.rb
 - lib/kward/hooks/catalog.rb
@@ -230,6 +242,8 @@ files:
 - lib/kward/memory/turn_context.rb
 - lib/kward/message_access.rb
 - lib/kward/message_text.rb
+- lib/kward/model/azure_openai_config.rb
+- lib/kward/model/catalog.rb
 - lib/kward/model/chat_invocation.rb
 - lib/kward/model/client.rb
 - lib/kward/model/context_overflow.rb
@@ -237,7 +251,9 @@ files:
 - lib/kward/model/copilot_models.rb
 - lib/kward/model/model_info.rb
 - lib/kward/model/payloads.rb
+- lib/kward/model/provider_catalog.rb
 - lib/kward/model/retry_message.rb
+- lib/kward/model/sources.rb
 - lib/kward/model/stream_parser.rb
 - lib/kward/openrouter_model_cache.rb
 - lib/kward/pan/index.html.erb
@@ -245,6 +261,7 @@ files:
 - lib/kward/pan/server.rb
 - lib/kward/path_guard.rb
 - lib/kward/permissions/policy.rb
+- lib/kward/plugin_chat_runtime.rb
 - lib/kward/plugin_registry.rb
 - lib/kward/private_file.rb
 - lib/kward/project_files.rb
@@ -354,6 +371,7 @@ files:
 - lib/kward/tools/edit_file.rb
 - lib/kward/tools/fetch_content.rb
 - lib/kward/tools/fetch_raw.rb
+- lib/kward/tools/git_commit.rb
 - lib/kward/tools/list_directory.rb
 - lib/kward/tools/mcp_tool.rb
 - lib/kward/tools/read_file.rb
@@ -369,6 +387,13 @@ files:
 - lib/kward/tools/web_search.rb
 - lib/kward/tools/write_file.rb
 - lib/kward/transcript_export.rb
+- lib/kward/transport.rb
+- lib/kward/transport/gateway.rb
+- lib/kward/transport/host.rb
+- lib/kward/transport/manager.rb
+- lib/kward/transport/plugin_chat_gateway.rb
+- lib/kward/transport/runtime.rb
+- lib/kward/transport/store.rb
 - lib/kward/update_check.rb
 - lib/kward/version.rb
 - lib/kward/workspace.rb