ask-agent 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6931fde5be098a92af7a2dc3ae106c97aa925535992a2ef354dfe76bbc79c819
-  data.tar.gz: 3772209146d3c64b1b8a1e1086cbdbfbf6464b6da844362aa4e63e8b16815b8b
+  metadata.gz: 4812b86203eb5a12eb03138de1e50fe8f0a80532f545bb683dcf051f2729c088
+  data.tar.gz: ba9e999b2aedae3e9c0f55067a35e3d3f29f828717a8f7129c0e0037bd518a33
 SHA512:
-  metadata.gz: 698c25a1cea3af3c46801b5da5bed336f1982b480200b133a730f259a90d7b0e4b5e038a703ff7a5672fee7ea57966bf405d1e2833046a31eea51d2334c73f2a
-  data.tar.gz: 2cce1e6b2c7afde036aa5d53f649c02722bf62e14c896d9fc08b07de7de6b2f3a59161dfd2e5bfa391a211c3794b582ee4243ae0f4eb9addf261f611ba1871c8
+  metadata.gz: a5b049b05acf1a82334a2169a708d60a6511db2d790ec5db3f30b9b4775a561eb204b8fdb209b60d095edeba43bd27f1572a909d78118eba9f295943625da370
+  data.tar.gz: 54ba99bbacd6152c52196f276f28559d2a13e09b048338c4c5198e9ab01c8f2cc9e5eb57c2a957b1ba6dea4410726c3eba644104b66d767729e908a10c366133

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.3.0] — 2026-07-17
+
+### Added
+
+- **Token and cost tracking** — `ResponseMessage` and `ChatChunk` now carry `input_tokens`, `output_tokens`, and `cost` fields. Token counts are extracted from provider responses and streaming chunks.
+- **Instrumentation events** — `Chat#ask` emits `chat.ask` and `chat.stream.ask` events via `Ask::Instrumentation`, unlocking the full monitoring pipeline (ask-agent → ask-instrumentation → ask-monitoring).
+- **Cost in agent events** — `SessionEnd` and `TurnEnd` events now include `input_tokens`, `output_tokens`, and `cost` fields, accumulated across all turns in the session.
+- **Cumulative session costs** — `Session` tracks `total_input_tokens`, `total_output_tokens`, and `total_cost` across all turns and reflection rounds.
+
+### Changed
+
+- **Dependency added** — `ask-instrumentation >= 0.1` added to gemspec. Instrumentation is optional (emission is wrapped in `defined?` check).
+- **Gemfile** — now uses local path resolution for sibling ask-* gems during development.
+
 ## [0.2.1] - 2026-06-25
 
 ### Changed

data/lib/ask/agent/chat.rb

@@ -3,47 +3,30 @@
 module Ask
   module Agent
     # Response message returned by {Chat#ask}.
-    # Presents a message-like response interface for ask-agent internal use.
-    ResponseMessage = Data.define(:content, :tool_calls, :thinking) do
+    # Includes token counts and cost when available from the provider.
+    ResponseMessage = Data.define(:content, :tool_calls, :thinking, :input_tokens, :output_tokens, :cost) do
       def tool_call? = !tool_calls.empty?
       def to_s = content.to_s
     end
 
-    # Tool call data used in {ResponseMessage} and {ChatChunk}.
     ToolCallInfo = Data.define(:id, :name, :arguments)
 
-    # Chunk yielded during streaming from {Chat#ask}.
-    ChatChunk = Data.define(:content, :tool_calls, :thinking) do
+    ChatChunk = Data.define(:content, :tool_calls, :thinking, :input_tokens, :output_tokens) do
       def tool_call? = !tool_calls.empty?
     end
 
-    # Thin wrapper around {Ask::Provider} + an internal message array that
-    # presents a Chat-like API for ask-agent internal use.
-    #
-    # Manages conversation history, resolves the correct provider/model,
-    # handles streaming chunk accumulation, and normalises tool call
-    # formats between Ask::Provider (Array of Hashes) and ask-agent
-    # internal usage (Hash of { id => ToolCallInfo }).
     class Chat
-      # @return [String] model ID (e.g. "gpt-4o")
-        attr_reader :model_id
-      # @return [String] model ID (e.g. "gpt-4o")
+      attr_reader :model_id
+
       def model
         @model_id
       end
-      # @return [Array<Ask::Message>] all messages in the conversation
+
       attr_reader :messages
 
-      # @param model [String, #ask] model ID or chat-like object
-      # @param tools [Array<Ask::Tool>] tool instances available to the chat
-      # @param temperature [Float, nil] sampling temperature
-      # @param schema [Ask::Schema, Hash, nil] structured output schema
-      # @param assume_model_exists [Boolean] whether to skip model catalog lookup
-      # @param provider [String, Symbol, nil] provider slug to use (overrides model catalog)
-      def initialize(model:, tools: [], temperature: nil, schema: nil,
-                     assume_model_exists: false, provider: nil, **)
+      def initialize(model:, tools: [], temperature: nil, schema: nil, provider: nil, **)
         @model_id = model.respond_to?(:id) ? model.id : model.to_s
-        @model_info = resolve_model(@model_id) unless assume_model_exists
+        @model_info = Ask::ModelCatalog.find(@model_id)
         @tools = tools
         @temperature = temperature
         @schema = schema
@@ -52,38 +35,39 @@ module Ask
         @provider = nil
       end
 
-      # Send a user message and get a completion response.
-      #
-      # @param message [String, nil] user message text
-      # @yield [ChatChunk] streaming chunks (only when a block is given)
-      # @return [ResponseMessage] the assistant's response
       def ask(message = nil, &block)
         @messages << Ask::Message.new(role: :user, content: message.to_s) if message
 
         stream = block_given?
         tool_defs = @tools.map { |t| Ask::ToolDef.from_tool(t) }
 
-        # Accumulator for tool calls during streaming (keyed by index)
         calls_acc = {}
 
-        result = provider.chat(          @messages.map(&:to_h),
-          model: @model_id,
-          tools: tool_defs,
-          temperature: @temperature,
+        provider_model = @model_id
+        provider_tools = tool_defs
+        provider_temp = @temperature
+        provider_schema = @schema&.respond_to?(:to_json_schema) ? @schema.to_json_schema : @schema
+        provider_params = @extra_params || {}
+
+        result = provider.chat(
+          @messages.map(&:to_h),
+          model: provider_model,
+          tools: provider_tools,
+          temperature: provider_temp,
           stream: stream,
-          schema: @schema&.respond_to?(:to_json_schema) ? @schema.to_json_schema : @schema,
-          **(@extra_params || {})
+          schema: provider_schema,
+          **provider_params
         ) do |raw_chunk|
           next unless block_given?
 
-          # Accumulate tool calls by index during streaming
           accumulate_tool_calls(raw_chunk, calls_acc)
 
-          # Yield adapted chunk with current tool call state
           yield ChatChunk.new(
             content: raw_chunk.content,
             tool_calls: build_current_tool_calls(calls_acc),
-            thinking: raw_chunk.respond_to?(:thinking) ? raw_chunk.thinking : nil
+            thinking: raw_chunk.respond_to?(:thinking) ? raw_chunk.thinking : nil,
+            input_tokens: nil,
+            output_tokens: nil
           )
         end
 
@@ -93,24 +77,24 @@ module Ask
           build_response(result)
         end
 
-        # Store assistant response in conversation history
         @messages << Ask::Message.new(
           role: :assistant,
           content: response_msg.content,
           tool_calls: response_msg.tool_calls&.values&.map { |tc|
             { id: tc.id, type: "function", name: tc.name, arguments: tc.arguments }
-          }
+          },
+          metadata: {
+            input_tokens: response_msg.input_tokens,
+            output_tokens: response_msg.output_tokens,
+            cost: response_msg.cost
+          }.compact
         )
 
+        emit_instrumentation(stream, response_msg)
+
         response_msg
       end
 
-      # Add a message to the conversation history.
-      #
-      # @param role [Symbol] :system, :user, :assistant, :tool
-      # @param content [String, nil] message content
-      # @param tool_call_id [String, nil] tool call ID (for tool results)
-      # @param tool_calls [Array<Hash>, nil] tool call invocations
       def add_message(role:, content: nil, tool_call_id: nil, tool_calls: nil)
         @messages << Ask::Message.new(
           role: role,
@@ -120,58 +104,34 @@ module Ask
         )
       end
 
-      # Set or replace the system prompt.
-      #
-      # @param prompt [String] system instructions
-      # @return [self]
       def with_instructions(prompt)
         @messages.reject! { |m| m.role == :system }
         @messages.unshift(Ask::Message.new(role: :system, content: prompt))
         self
       end
 
-      # Set the structured output schema and return self.
-      #
-      # @param schema [Ask::Schema, Hash] structured output schema
-      # @return [self]
-  # Set additional parameters for the provider call and return self.
-  #
-  # @param params [Hash] extra parameters passed to the provider
-  # @return [self]
-  def with_params(**params)
-    @extra_params = (@extra_params || {}).merge(params)
-    self
-  end
+      def with_params(**params)
+        @extra_params = (@extra_params || {}).merge(params)
+        self
+      end
 
-        # Set additional parameters forwarded to the provider call.
-  # @param params [Hash] extra keyword arguments for the provider
-  # @return [self]
-def with_schema(schema)
+      def with_schema(schema)
         @schema = schema.respond_to?(:to_json_schema) ? schema.to_json_schema : schema
         self
       end
 
-      # Clear all messages from the conversation.
       def reset_messages!
         @messages.clear
       end
 
       private
 
-      # Resolve model info from the catalog.
-      def resolve_model(model_id)
-        Ask::ModelCatalog.find(model_id)
-      rescue Ask::ModelNotFound
-        nil
-      end
-
-      # Lazily resolve and instantiate the LLM provider.
       def provider
         @provider ||= build_provider
       end
 
       def build_provider
-        slug = @provider_override&.to_s || @model_info&.provider || "openai"
+        slug = @provider_override&.to_s || @model_info.provider
         klass = Ask::Provider.resolve(slug)
         klass.new(provider_config(slug))
       end
@@ -185,7 +145,6 @@ def with_schema(schema)
         Ask::LLM::Config.new(config)
       end
 
-      # Accumulate partial tool calls from streaming chunks.
       def accumulate_tool_calls(raw_chunk, calls_acc)
         return unless raw_chunk.tool_call?
 
@@ -198,7 +157,6 @@ def with_schema(schema)
         end
       end
 
-      # Build current snapshot of tool calls from accumulator.
       def build_current_tool_calls(calls_acc)
         hash = {}
         calls_acc.each_value do |tc_data|
@@ -212,7 +170,6 @@ def with_schema(schema)
         hash
       end
 
-      # Convert Ask::Provider tool_calls (Array of Hashes) to Hash.
       def build_tool_call_hash(raw_calls)
         hash = {}
         raw_calls.each do |tc|
@@ -227,21 +184,76 @@ def with_schema(schema)
         hash
       end
 
-      # Build response from streaming result.
       def build_stream_response(stream, calls_acc)
-        thinking = stream.chunks.filter_map(&:thinking).last
+        tokens = accumulated_tokens(stream)
+        cost = calculate_cost(tokens[:input], tokens[:output])
         ResponseMessage.new(
           content: stream.accumulated_text,
           tool_calls: build_current_tool_calls(calls_acc),
-          thinking: thinking
+          thinking: stream.chunks.filter_map(&:thinking).last,
+          input_tokens: tokens[:input],
+          output_tokens: tokens[:output],
+          cost: cost
         )
       end
 
-      # Build response from non-streaming result.
       def build_response(msg)
         tool_calls = msg.tool_calls ? build_tool_call_hash(msg.tool_calls) : {}
         thinking = msg.respond_to?(:thinking) ? msg.thinking : nil
-        ResponseMessage.new(content: msg.content.to_s, tool_calls: tool_calls, thinking: thinking)
+        metadata = msg.metadata || {}
+        input_tokens = metadata[:input_tokens] || metadata["input_tokens"]
+        output_tokens = metadata[:output_tokens] || metadata["output_tokens"]
+        cost = calculate_cost(input_tokens, output_tokens)
+        ResponseMessage.new(
+          content: msg.content.to_s,
+          tool_calls: tool_calls,
+          thinking: thinking,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          cost: cost
+        )
+      end
+
+      def accumulated_tokens(stream)
+        input = 0
+        output = 0
+        stream.chunks.each do |chunk|
+          if chunk.usage
+            input = chunk.usage[:input_tokens] || chunk.usage["input_tokens"] || input
+            output = chunk.usage[:output_tokens] || chunk.usage["output_tokens"] || output
+          end
+          output += 1 if chunk.content.to_s.length > 0
+        end
+        { input: input, output: output }
+      end
+
+      def calculate_cost(input_tokens, output_tokens)
+        return nil unless input_tokens || output_tokens
+        Ask::LLM::CostCalculator.calculate(@model_info, input_tokens: input_tokens || 0, output_tokens: output_tokens || 0)
+      rescue StandardError
+        nil
+      end
+
+      def emit_instrumentation(stream, response_msg)
+        return unless defined?(Ask::Instrumentation)
+
+        payload = {
+          model: @model_id,
+          provider: @model_info.provider,
+          input_tokens: response_msg.input_tokens,
+          output_tokens: response_msg.output_tokens,
+          cost: response_msg.cost,
+          tool_calls: response_msg.tool_call?,
+          stream: stream
+        }.compact
+
+        if stream
+          Ask::Instrumentation.instrument("chat.stream.ask", payload)
+        else
+          Ask::Instrumentation.instrument("chat.ask", payload)
+        end
+      rescue StandardError
+        nil
       end
     end
   end

data/lib/ask/agent/events.rb

@@ -4,10 +4,10 @@ module Ask
   module Agent
     module Events
       SessionStart = Data.define
-      SessionEnd = Data.define(:result, :turn_count, :tool_calls_made)
+      SessionEnd = Data.define(:result, :turn_count, :tool_calls_made, :input_tokens, :output_tokens, :cost)
 
       TurnStart = Data.define
-      TurnEnd = Data.define(:tool_results, :turn_number)
+      TurnEnd = Data.define(:tool_results, :turn_number, :input_tokens, :output_tokens, :cost)
 
       MessageStart = Data.define
       TextDelta = Data.define(:content)

data/lib/ask/agent/loop.rb

@@ -6,7 +6,7 @@ module Ask
       LOOP_DETECTION_WINDOW = 3
       @max_consecutive_tool_turns = 6
 
-      attr_reader :turn_count
+      attr_reader :turn_count, :last_input_tokens, :last_output_tokens, :last_cost
 
       def initialize(max_turns: 25, max_consecutive_tool_turns: 6)
         @max_turns = max_turns
@@ -36,6 +36,10 @@ module Ask
           end
         end
 
+        @last_input_tokens = response.input_tokens
+        @last_output_tokens = response.output_tokens
+        @last_cost = response.cost
+
         event_emitter.emit(Events::MessageEnd.new(tool_calls: response.tool_call?))
         @turn_count += 1
 
@@ -65,7 +69,13 @@ module Ask
           return "Based on my investigation: #{summary}"
         end
 
-        event_emitter.emit(Events::TurnEnd.new(tool_results: tool_results, turn_number: @turn_count))
+        event_emitter.emit(Events::TurnEnd.new(
+          tool_results: tool_results,
+          turn_number: @turn_count,
+          input_tokens: @last_input_tokens,
+          output_tokens: @last_output_tokens,
+          cost: @last_cost
+        ))
 
         if compactor && compactor.should_compact?
           compactor.run(event_emitter: event_emitter)

data/lib/ask/agent/session.rb

@@ -7,7 +7,7 @@ module Ask
   module Agent
     class Session
       attr_reader :id, :chat, :tools, :turn_count, :created_at, :messages
-      attr_reader :tool_calls_made
+      attr_reader :tool_calls_made, :total_input_tokens, :total_output_tokens, :total_cost
 
       def reflection_count
         @reflector&.reflection_count || 0
@@ -33,6 +33,10 @@ module Ask
         @created_at = Time.now
         @_no_tools_instructed = false
 
+        @total_input_tokens = 0
+        @total_output_tokens = 0
+        @total_cost = 0.0
+
         @telemetry = telemetry.is_a?(Telemetry) ? telemetry : Telemetry.new(enabled: !!telemetry)
 
         @chat = build_chat(model, system_prompt, tools, **chat_options)
@@ -99,6 +103,10 @@ module Ask
             event_emitter: self,
             session_id: @id
           )
+
+          @total_input_tokens += @loop.last_input_tokens.to_i
+          @total_output_tokens += @loop.last_output_tokens.to_i
+          @total_cost += @loop.last_cost.to_f
         rescue MaxTurnsExceeded => e
           emit(Events::MaxTurnsExceeded.new(max_turns: @max_turns))
           @telemetry.log(:max_turns_exceeded, session_id: @id, max_turns: @max_turns)
@@ -143,6 +151,10 @@ module Ask
               event_emitter: self,
               session_id: @id
             )
+
+            @total_input_tokens += @loop.last_input_tokens.to_i
+            @total_output_tokens += @loop.last_output_tokens.to_i
+            @total_cost += @loop.last_cost.to_f
           end
         end
 
@@ -151,7 +163,14 @@ module Ask
           try_auto_meta_agent
         end
 
-        emit(Events::SessionEnd.new(result: response, turn_count: @turn_count, tool_calls_made: @tool_calls_made))
+        emit(Events::SessionEnd.new(
+          result: response,
+          turn_count: @turn_count,
+          tool_calls_made: @tool_calls_made,
+          input_tokens: @total_input_tokens,
+          output_tokens: @total_output_tokens,
+          cost: @total_cost
+        ))
         @messages = @chat.messages.dup
 
         response

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.2.1"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -65,6 +65,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: ask-instrumentation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement