ask-agent 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14e351edbbd119bd5ae5bf8701fd38dd1370b496a415d6be9bc386cb3c5bb04b
-  data.tar.gz: 4a156a06a909b8725685ec7cb5bff121e46b2ebcb2976b6411cb4c29c75ab364
+  metadata.gz: bb1a00c9b6f32029b7d27271482fe82dfa7333601776537a38160635bf4fde0b
+  data.tar.gz: 80d666d9485e6e058c9a81d20fdbfa48b4b196a33d1675655fbbd7f6ffea9240
 SHA512:
-  metadata.gz: 852a51b092bbe1d4e3a2b57c87001474261d413428ab83bb4a71fae4858a229e0c9a9d337c24a89177773c1b2ee82a8aac8069455f2f1191350d0d66c19a477f
-  data.tar.gz: ca6761470ac7c95191bf7e2bd49c47bf10a71fd0ba6796468ddc113692f5f685f6a73d57f9fe46cf7fc6295f6b3c7aa11806212b62d8c18f60562888bcd7d4c0
+  metadata.gz: d7ef76f83baba0df18a1f60a6a00aae8cefb0b191ccf6eb0d5b680ed68e0c305dde891591673805b28bec5705ae632da2bd6acc4bd5810602a3b04878483f890
+  data.tar.gz: 639f577894d439805d0f06d988c4b528241f82b31656dea7b9a28ba54eca173c4262e3a48b865705bfb0ae153653c9a9c4e4ac6fc3cd7cb8fe02c92efe4495f9

data/CHANGELOG.md

@@ -1,3 +1,58 @@
+## [0.12.0] — 2026-07-22
+
+### Added
+
+- **System Context algebra** — typed, independently-observable context sources
+  that compose into the system prompt. Each source has a unique key, a `load`
+  function, a `baseline` render for initialization, and an `update` render for
+  mid-conversation changes.
+
+- **Built-in context sources:**
+  - `Instructions` — agent's core system prompt / instructions.md
+  - `SkillsList` — "## Available Skills" listing from the skills registry
+  - `AlwaysActiveSkills` — full instructions for skills with `always: true`
+  - `Date` — today's date in ISO 8601 format
+
+- **`SystemContext#changes`** — detects which sources have changed since the
+  last snapshot and returns update texts. Enables mid-conversation updates
+  (e.g., date rollover, skill registry changes) without rebuilding the entire
+  prompt.
+
+- **`Ask::Agent::ContextSource` base class** — DSL for defining typed context
+  sources with `key`, `load`, `baseline`, and optional `update`.
+
+- **`Session` uses SystemContext** — the system prompt is now assembled from
+  typed sources instead of string concatenation, with 17 tests covering
+  rendering, change detection, and source composition.
+
+## [0.11.0] — 2026-07-22
+
+### Added
+
+- **`Definition#parallel_tools` DSL** — set parallel tool execution per agent:
+  ```ruby
+  class MyAgent < Ask::Agent::Definition
+    model "gpt-4o"
+    parallel_tools false
+  end
+  ```
+  Defaults to `true`.
+
+- **`Definition#option` DSL** — pass arbitrary Session options:
+  ```ruby
+  class MyAgent < Ask::Agent::Definition
+    model "gpt-4o"
+    option :temperature, 0.7
+    option :reflector, true
+  end
+  ```
+
+- **17 new tests** for Definition DSL — model, provider, max_turns, parallel_tools, tools, schedule, option, instructions_path, instructions_content, subclass tracking.
+
+### Fixed
+
+- **`build_session_from_definition` passes `parallel_tools` and custom options** to `Session.new`. Previously only `model`, `provider`, and `max_turns` were forwarded.
+
 ## [0.10.0] — 2026-07-21
 
 ### Added

data/lib/ask/agent/context_source.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    # A typed, independently observable piece of the system context.
+    #
+    # Each source has a unique +key+, a +load+ function that returns its
+    # current value, a +baseline+ render for initial prompt inclusion,
+    # and an +update+ render for mid-conversation change notifications.
+    #
+    # @example
+    #   class DateSource < Ask::Agent::ContextSource
+    #     key "core/date"
+    #
+    #     def load
+    #       Date.today.iso8601
+    #     end
+    #
+    #     def baseline(date)
+    #       "Today is #{date}."
+    #     end
+    #
+    #     def update(prev, curr)
+    #       "Earlier I said the date was #{prev}, but it is now #{curr}."
+    #     end
+    #   end
+    class ContextSource
+      class << self
+        # Unique namespaced key for this source (e.g., "core/date").
+        # Used for change detection and deterministic ordering.
+        def key(value = :__no_value__)
+          if value == :__no_value__
+            @key
+          else
+            @key = value
+          end
+        end
+
+        def inherited(subclass)
+          super
+          # Register source type for discovery
+          @registered_sources ||= []
+          @registered_sources << subclass
+        end
+
+        def registered_sources
+          @registered_sources || []
+        end
+      end
+
+      # @return [String] unique key for this source
+      def key
+        self.class.key
+      end
+
+      # Load the current value of this source.
+      # @return [Object] any value that will be passed to +baseline+ and +update+
+      def load
+        raise NotImplementedError
+      end
+
+      # Render the initial text for this source.
+      # @param value [Object] the value returned by +load+
+      # @return [String]
+      def baseline(value)
+        raise NotImplementedError
+      end
+
+      # Render a mid-conversation update message.
+      # Called when +load+ returns a value different from the previous one.
+      # @param previous [Object] the value from the last load
+      # @param current [Object] the current value
+      # @return [String, nil] nil if no update is needed
+      def update(previous, current)
+        nil
+      end
+    end
+  end
+end

data/lib/ask/agent/context_sources.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module ContextSources
+      # The agent's core instructions (system prompt / instructions.md).
+      class Instructions < Ask::Agent::ContextSource
+        key "core/instructions"
+
+        def initialize(content)
+          @content = content.to_s
+        end
+
+        def load
+          @content
+        end
+
+        def baseline(content)
+          content
+        end
+      end
+
+      # The "## Available Skills" listing from the skills registry.
+      # Only renders when the registry has skills to list.
+      class SkillsList < Ask::Agent::ContextSource
+        key "core/skills"
+
+        def initialize(registry)
+          @registry = registry
+        end
+
+        def load
+          @registry&.format_for_prompt.to_s
+        end
+
+        def baseline(listing)
+          listing.empty? ? nil : listing
+        end
+
+        def update(prev, curr)
+          return nil if prev == curr
+          return "Skills have been updated:\n#{curr}"
+        end
+      end
+
+      # Full instructions for always-active skills (those with +always: true+).
+      class AlwaysActiveSkills < Ask::Agent::ContextSource
+        key "core/skills.always_active"
+
+        def initialize(registry)
+          @registry = registry
+        end
+
+        def load
+          return "" unless @registry
+
+          @registry.always_active_skills.map { |s|
+            "## Skill: #{s.name}\n#{s.description}\n\n#{s.instructions}"
+          }.join("\n\n")
+        end
+
+        def baseline(instructions)
+          instructions.empty? ? nil : instructions
+        end
+      end
+
+      # Today's date in ISO 8601 format.
+      class Date < Ask::Agent::ContextSource
+        key "core/date"
+
+        def load
+          ::Date.today.iso8601
+        end
+
+        def baseline(date)
+          "Today's date is #{date}."
+        end
+
+        def update(prev, curr)
+          "I previously said the date was #{prev}, but it is now #{curr}."
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/session.rb

@@ -48,24 +48,10 @@ module Ask
         @compactor = compactor ? build_compactor(compactor) : nil
         @hooks = Hooks.new(hooks)
 
-        # Auto-discover skills (shared + per-agent if agent_dir is given)
-        @skills_registry = Ask::Skills.discover(agent_dir: @agent_dir) rescue nil
-        if @skills_registry && !@skills_registry.names.empty?
-          skill_text = @skills_registry.format_for_prompt
-          if !skill_text.empty? && @chat.messages.any? { |m| m.role == :system }
-            current = @chat.messages.find { |m| m.role == :system }.content.to_s
-
-            # Append skill listing
-            augmented = current + skill_text
-
-            # Auto-inject full instructions for always-active skills
-            @skills_registry.always_active_skills.each do |skill|
-              augmented += "\n\n## Skill: #{skill.name}\n#{skill.description}\n\n#{skill.instructions}"
-            end
+        # Build system context from typed sources
+        @system_context = build_system_context(system_prompt)
+        apply_system_context
 
-            @chat.with_instructions(augmented)
-          end
-        end
         @persistence = persistence
 
         reflector_opts = reflector.is_a?(Hash) ? reflector : {}
@@ -355,6 +341,32 @@ module Ask
           .select { |m| m.role == :assistant && m.content.to_s.strip.length > 0 }
           .first&.content.to_s
       end
+
+      # Build the system context from typed sources.
+      def build_system_context(prompt)
+        sources = []
+        sources << Ask::Agent::ContextSources::Instructions.new(prompt) if prompt
+
+        # Auto-discover skills (shared + per-agent if agent_dir is given)
+        @skills_registry = Ask::Skills.discover(agent_dir: @agent_dir) rescue nil
+        if @skills_registry && !@skills_registry.names.empty?
+          sources << Ask::Agent::ContextSources::SkillsList.new(@skills_registry)
+          if @skills_registry.always_active_skills.any?
+            sources << Ask::Agent::ContextSources::AlwaysActiveSkills.new(@skills_registry)
+          end
+        end
+
+        SystemContext.new(sources)
+      end
+
+      # Render the system context and apply it to the chat.
+      def apply_system_context
+        rendered = @system_context.render
+        return if rendered.empty?
+        return unless @chat.messages.any? { |m| m.role == :system }
+
+        @chat.with_instructions(rendered)
+      end
     end
   end
 end

data/lib/ask/agent/system_context.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    # Composes typed context sources into a coherent system prompt.
+    #
+    # At initialization, each source renders its +baseline+ text. Sources
+    # are ordered by their +key+ for deterministic output.
+    #
+    # At any point, +changes+ returns a list of update texts for sources
+    # whose values have changed since the last snapshot. This enables
+    # mid-conversation updates without rebuilding the entire prompt.
+    #
+    # @example
+    #   ctx = SystemContext.new([
+    #     InstructionsSource.new("You are a helper."),
+    #     SkillsListSource.new(registry),
+    #     DateSource.new,
+    #   ])
+    #
+    #   prompt = ctx.render     # full system prompt
+    #   updates = ctx.changes   # nil if nothing changed
+    class SystemContext
+      Snapshot = Data.define(:key, :value)
+
+      def initialize(sources)
+        @sources = sources
+        @snapshots = {}
+        take_snapshot
+      end
+
+      # Render the full baseline system prompt.
+      # @return [String]
+      def render
+        parts = @sources.map do |source|
+          value = @snapshots[source.key]&.value
+          text = source.baseline(value) rescue nil
+          text
+        end
+        parts.compact.join("\n\n")
+      end
+
+      # Detect changes since the last snapshot.
+      # Returns update texts for sources whose value changed, or nil.
+      # @return [Array<String>, nil]
+      def changes
+        updates = []
+        @sources.each do |source|
+          prev_value = @snapshots[source.key]&.value
+          current_value = source.load
+          next if prev_value == current_value
+
+          update_text = source.update(prev_value, current_value)
+          updates << update_text if update_text
+          @snapshots[source.key] = Snapshot.new(key: source.key, value: current_value)
+        end
+        updates.any? ? updates : nil
+      end
+
+      # Access a source by key.
+      # @param key [String]
+      # @return [ContextSource, nil]
+      def [](key)
+        @sources.find { |s| s.key == key }
+      end
+
+      private
+
+      def take_snapshot
+        @sources.each do |source|
+          value = source.load
+          @snapshots[source.key] = Snapshot.new(key: source.key, value: value)
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.11.0"
+    VERSION = "0.12.0"
   end
 end

data/lib/ask/agent.rb

@@ -222,6 +222,9 @@ end
 
 require_relative "agent/version"
 require_relative "agent/events"
+require_relative "agent/system_context"
+require_relative "agent/context_source"
+require_relative "agent/context_sources"
 require_relative "agent/chat"
 require_relative "agent/telemetry"
 require_relative "agent/tool_abort_controller"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -154,6 +154,8 @@ files:
 - lib/ask/agent/cli.rb
 - lib/ask/agent/compactor.rb
 - lib/ask/agent/configuration.rb
+- lib/ask/agent/context_source.rb
+- lib/ask/agent/context_sources.rb
 - lib/ask/agent/definition.rb
 - lib/ask/agent/events.rb
 - lib/ask/agent/extensions/audit_log.rb
@@ -178,6 +180,7 @@ files:
 - lib/ask/agent/stream_transforms/pipeline.rb
 - lib/ask/agent/stream_transforms/text_buffer.rb
 - lib/ask/agent/stream_transforms/thinking_separator.rb
+- lib/ask/agent/system_context.rb
 - lib/ask/agent/telemetry.rb
 - lib/ask/agent/test.rb
 - lib/ask/agent/tool_abort_controller.rb