ask-app-server 0.1.2 → 0.4.2

data/lib/ask/app_server/cli.rb

@@ -8,14 +8,16 @@ module Ask
     #
     # Usage:
     #   ask-app-server                   # Start in stdio mode (default)
-    #   ask-app-server --version         # Show version
-    #   ask-app-server --help            # Show help
-    #   ask-app-server --config PATH     # Use specific config file
+    #   ask-app-server --socket PATH    # Also listen on a unix socket (multi-client)
+    #   ask-app-server --version        # Show version
+    #   ask-app-server --help           # Show help
+    #   ask-app-server --config PATH    # Use specific config file
     #
     # Environment variables:
     #   ASK_APP_SERVER_CONFIG   - Path to config file (default: auto-detect)
     #   ASK_APP_SERVER_MODEL    - Model to use (overrides config file)
     #   ASK_APP_SERVER_PERMISSIONS - Permission mode (overrides config file)
+    #   ASK_APP_SERVER_SOCKET   - Unix socket path (same as --socket)
     #   DEBUG                   - Enable debug logging (1/0)
     class CLI
       def self.run!(args = ARGV)
@@ -32,14 +34,14 @@ module Ask
           return
         end
 
-        # Parse --config from args
+        # Parse --config and --socket from args
         config_path = nil
-        remaining_args = []
+        socket_path = nil
         args.each_with_index do |arg, i|
           if arg == "--config" && i + 1 < args.length
             config_path = args[i + 1]
-          elsif !arg.start_with?("--config")
-            remaining_args << arg
+          elsif arg == "--socket" && i + 1 < args.length
+            socket_path = args[i + 1]
           end
         end
 
@@ -66,21 +68,34 @@ module Ask
           permission_timeout: config.permission_timeout
         )
 
-        # Start the server
-        server = Server.new(session_manager: session_manager)
-
-        # Wire the server as the protocol sender for permission requests.
-        # Every time a new session is created with a PermissionHandler,
-        # the server registers its outgoing request callback.
-        session_manager.on_new_permission_handler do |handler|
-          server.register_permission_handler(handler)
+        # Pane integration: when running inside a terminal workspace,
+        # keep its agent-state sidebar accurate from first-party host
+        # events.
+        herdr_reporter = HerdrReporter.attach(session_manager)
+
+        # Optional unix-socket transport for multi-client attach (runs
+        # alongside the stdio transport, sharing the session manager).
+        socket_path ||= ENV["ASK_APP_SERVER_SOCKET"]
+        socket_server = nil
+        if socket_path
+          socket_server = SocketServer.new(session_manager: session_manager, socket_path: socket_path)
+          socket_server.start
+          $stderr.puts "socket:    #{socket_server.socket_path}"
         end
 
+        # Start the server (stdio transport, blocks)
+        server = Server.new(session_manager: session_manager)
+
         begin
           server.start
         rescue Interrupt
           $stderr.puts "\n[ask-app-server] Shutting down..." if config.debug?
+        ensure
+          # Clean up on Ctrl-C AND on normal exit (stdin EOF): the socket
+          # file must not outlive the host.
           server.stop
+          socket_server&.stop
+          herdr_reporter&.close
         end
       end
 
@@ -115,7 +130,7 @@ module Ask
           ask-app-server v#{Ask::AppServer::VERSION}
 
           JSON-RPC/stdio app-server for ask-rb agents.
-          Drop-in compatible with the ZCode/Codex app-server protocol.
+          Drop-in compatible with the app-server protocol.
 
           USAGE:
             ask-app-server                  Start in stdio mode

data/lib/ask/app_server/connection.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module AppServer
+    # A client connection to the session host: an input/output pair (stdio
+    # or a unix socket) plus the connection's per-session event delivery
+    # cursors.
+    #
+    # Delivery is cursor-based: the connection tracks the last delivered
+    # seq for each subscribed session, so any number of clients can attach
+    # to the same sessions and each receives exactly the events after its
+    # own cursor. Subscribe with afterSeq to replay; clients dedup by seq.
+    class Connection
+      # session_id => last delivered seq
+      attr_reader :subscriptions
+
+      # @param input [IO] source of NDJSON lines (responds to gets)
+      # @param output [IO] sink for NDJSON responses/notifications
+      def initialize(input, output)
+        @input = input
+        @output = output
+        @subscriptions = {}
+        @mutex = Mutex.new
+      end
+
+      # Read one line from the input, or nil on EOF/disconnect.
+      def read_line
+        @input.gets
+      end
+
+      # Write one JSON-RPC message (Hash) to the output.
+      def write(msg)
+        @output.puts(JSON.generate(msg))
+        @output.flush
+      end
+
+      # Whether the connection is subscribed to a session.
+      def subscribed?(session_id)
+        @mutex.synchronize { @subscriptions.key?(session_id) }
+      end
+
+      # Subscribe to a session, starting delivery after after_seq.
+      def subscribe(session_id, after_seq: 0)
+        @mutex.synchronize { @subscriptions[session_id] = after_seq.to_i }
+      end
+
+      # Unsubscribe from a session.
+      def unsubscribe(session_id)
+        @mutex.synchronize { @subscriptions.delete(session_id) }
+      end
+
+      # The last delivered seq for a session (0 = replay from the start).
+      def cursor(session_id)
+        @mutex.synchronize { @subscriptions[session_id] || 0 }
+      end
+
+      # Advance the delivery cursor for a session (only while subscribed).
+      def advance(session_id, seq)
+        @mutex.synchronize do
+          @subscriptions[session_id] = seq if @subscriptions.key?(session_id)
+        end
+      end
+
+      # Drop all subscriptions. Does not close the underlying I/O — the
+      # owner (the server) manages IO lifecycle.
+      def close
+        @mutex.synchronize { @subscriptions.clear }
+      end
+    end
+  end
+end

data/lib/ask/app_server/event_translator.rb

@@ -4,89 +4,124 @@ require "securerandom"
 
 module Ask
   module AppServer
-    # Translates ask-agent Events into app-server protocol events.
+    # Translates ask-agent runtime events into canonical
+    # Ask::SessionProtocol events (the contract between the host and every
+    # client). Every emitted event is validated against the protocol
+    # registry, so a malformed translation fails fast at the boundary.
     #
-    # ask-agent emits events like TurnStart, TextDelta, ToolExecutionStart, etc.
-    # The app-server protocol uses a different set: turn.started, model.streaming,
-    # tool.updated, turn.completed, turn.failed, message.upserted.
-    #
-    # This class maps between the two models, emitting app-server protocol events
-    # that clients such as the Python Telegram bot and Vercel AI SDK expect.
+    # The translator owns the per-session event buffer and sequence
+    # numbers: clients poll (`session/events` after seq N) or subscribe
+    # (the server pushes drained events as `session/event` notifications).
     class EventTranslator
-      attr_reader :session_id, :turn_id
-
-      def initialize(session_id)
-        @session_id = session_id
-        @turn_id = nil
-        @seq = 0
+      # Events retained per session for replay/polling. Cursor-based
+      # delivery means the log is append-only; clients with cursors older
+      # than the cap miss the dropped events (durable log is a host
+      # storage concern).
+      MAX_EVENTS = 2000
+
+      # Optional observer called with every emitted canonical Event.
+      # This is the single choke point for all session events (translations
+      # plus approval/plan/session-lifecycle emissions), so host-side
+      # side effects (e.g. the pane reporter) hook here.
+      attr_accessor :on_event
+
+      def initialize
         @events = []
-        @streaming_text = +""
+        @seq = 0
+        @turn_id = nil
         @turn_active = false
-        @in_reflection = false
+        @streaming_text = +""
+        @plan_interaction_id = nil
       end
 
-      # Translate an ask-agent event into zero or more app-server events.
-      # Returns an array of event hashes (may be empty).
+      # Translate one ask-agent event into zero or more canonical events.
+      # Returns an array of Ask::SessionProtocol::Events::Event (may be
+      # empty); events are buffered for delivery.
       def translate(agent_event)
         case agent_event
         when Ask::Agent::Events::TurnStart
-          translate_turn_start
+          turn_started
         when Ask::Agent::Events::TextDelta
-          translate_text_delta(agent_event)
+          text_delta(agent_event)
+        when Ask::Agent::Events::ThinkingDelta
+          thinking_delta(agent_event)
         when Ask::Agent::Events::ToolCallDelta
-          # ToolCallDelta is informational; we track calls but don't emit
-          # until execution actually starts.
+          # Informational; execution events carry the tool lifecycle.
           []
         when Ask::Agent::Events::ToolExecutionStart
-          translate_tool_start(agent_event)
+          tool_start(agent_event)
         when Ask::Agent::Events::ToolExecutionUpdate
-          translate_tool_update(agent_event)
+          tool_update(agent_event)
         when Ask::Agent::Events::ToolExecutionEnd
-          translate_tool_end(agent_event)
-        when Ask::Agent::Events::MessageEnd
-          # Fires after the LLM response is complete (before tool execution).
-          # Not mapped directly; we already streamed the text.
-          []
-        when Ask::Agent::Events::TurnEnd
-          # Fires after tool execution completes for one recursive iteration.
-          # The session may continue with more tool calls.
-          []
-        when Ask::Agent::Events::ReflectionStart
-          # Reflection is an internal detail — skip
-          @in_reflection = true
-          []
-        when Ask::Agent::Events::ReflectionDelta
-          # Treat reflection text as regular model output
-          translate_text_delta(agent_event)
-        when Ask::Agent::Events::ReflectionEnd
-          @in_reflection = false
-          []
-        when Ask::Agent::Events::CompactionStart
-          []
-        when Ask::Agent::Events::CompactionEnd
-          []
-        when Ask::Agent::Events::Error
-          translate_error(agent_event)
-        when Ask::Agent::Events::SessionEnd
-          translate_session_end(agent_event)
+          tool_end(agent_event)
+        when Ask::Agent::Events::TodoUpdated
+          todos_updated(agent_event)
+        when Ask::Agent::Events::PlanProposed
+          plan_proposed(agent_event)
+        when Ask::Agent::Events::PlanApproved
+          plan_approved(agent_event)
+        when Ask::Agent::Events::PlanRejected
+          plan_rejected(agent_event)
         when Ask::Agent::Events::MaxTurnsExceeded
-          translate_turn_failed("Max turns exceeded (#{agent_event.max_turns})")
+          turn_failed("Max turns exceeded (#{agent_event.max_turns})")
         when Ask::Agent::Events::LoopDetected
-          translate_turn_failed("Loop detected on tool: #{agent_event.tool_name}")
+          turn_failed("Loop detected on tool: #{agent_event.tool_name}")
+        when Ask::Agent::Events::Error
+          error(agent_event)
+        when Ask::Agent::Events::SessionEnd
+          session_end(agent_event)
         else
+          # TurnEnd, MessageStart/End, Reflection*, Compaction*,
+          # SessionRolledBack/Forked, Evaluation*, MetaAgentAnalysis —
+          # internal detail, no canonical representation.
           []
         end
       end
 
-      # All events emitted since last poll.
+      # ── Queue/plan-driven emission (not ask-agent events) ──────────────
+
+      # An approval action was queued: emit approval.required.
+      #
+      # @param action [Ask::Agent::ApprovalQueue::Action]
+      def approval_required(action)
+        payload = { "toolName" => action.tool_name.to_s }
+        payload["args"] = action.args if action.args
+        payload["message"] = action.message if action.message
+        payload["autoApprovable"] = action.auto_approvable unless action.auto_approvable.nil?
+        emit("approval.required", payload.merge("id" => "act_#{action.id}"))
+      end
+
+      # An approval action changed status: emit approval.updated.
+      #
+      # @param action [Ask::Agent::ApprovalQueue::Action]
+      def approval_updated(action)
+        status = action.status.to_s
+        return unless %w[approved rejected].include?(status)
+
+        emit("approval.updated", { "id" => "act_#{action.id}", "status" => status })
+      end
+
+      # A session was created: emit session.created.
+      def session_created(session_id)
+        emit("session.created", { "sessionId" => session_id })
+      end
+
+      # A session ended: emit session.ended.
+      def session_ended(session_id, reason: "closed")
+        emit("session.ended", { "sessionId" => session_id, "reason" => reason })
+      end
+
+      # ── Buffer access ──────────────────────────────────────────────────
+
+      # All events since the last drain.
       def pending_events
         @events
       end
 
       # Drain and return all pending events, clearing the buffer.
       def drain_events
-        evs = @events.dup
-        @events.clear
+        evs = @events
+        @events = []
         evs
       end
 
@@ -95,99 +130,120 @@ module Ask
         @seq
       end
 
+      # Events after a given sequence number.
+      def events_after(after_seq)
+        @events.select { |e| e.seq > after_seq }
+      end
+
       private
 
       def next_seq
         @seq += 1
-        @seq
       end
 
-      def translate_turn_start
+      def turn_started
         @turn_id = SecureRandom.uuid
         @turn_active = true
         @streaming_text = +""
-
-        ev = build_event("turn.started", { turnId: @turn_id })
-        [ev]
+        emit("turn.started", { "turnId" => @turn_id })
       end
 
-      def translate_text_delta(event)
+      def text_delta(event)
         content = event.content.to_s
         return [] if content.empty?
 
         @streaming_text << content
+        emit("model.streaming", { "delta" => content })
+      end
+
+      def thinking_delta(event)
+        content = event.content.to_s
+        return [] if content.empty?
+
+        emit("model.thinking", { "delta" => content })
+      end
 
-        ev = build_event("model.streaming", { delta: content })
-        [ev]
+      def tool_start(event)
+        payload = {
+          "id" => event.id.to_s,
+          "name" => event.name.to_s,
+          "args" => event.arguments
+        }
+        emit("tool.use", payload)
       end
 
-      def translate_tool_start(event)
-        ev = build_event("tool.updated", {
-          toolName: event.name,
-          kind: "started",
-          input: event.arguments
-        })
-        [ev]
+      def tool_update(event)
+        payload = {
+          "id" => event.id.to_s,
+          "name" => event.name.to_s,
+          "partial" => event.partial_result.to_s
+        }
+        emit("tool.delta", payload)
       end
 
-      def translate_tool_update(event)
-        ev = build_event("tool.updated", {
-          toolName: event.name,
-          kind: "updated",
-          output: event.partial_result.to_s
-        })
-        [ev]
+      def tool_end(event)
+        payload = {
+          "id" => event.id.to_s,
+          "name" => event.name.to_s,
+          "output" => event.result,
+          "isError" => !!event.is_error,
+          "durationMs" => event.duration_ms
+        }
+        emit("tool.result", payload)
       end
 
-      def translate_tool_end(event)
-        kind = event.is_error ? "failed" : "completed"
-        ev = build_event("tool.updated", {
-          toolName: event.name,
-          kind: kind,
-          output: event.result.to_s,
-          durationMs: event.duration_ms
-        })
-        [ev]
+      def todos_updated(event)
+        todos = event.todos.map { |entry| entry.to_h.transform_keys(&:to_s) }
+        emit("todos.updated", { "todos" => todos })
       end
 
-      def translate_session_end(event)
-        @turn_active = false
-        response_text = event.result.to_s
+      def plan_proposed(event)
+        @plan_interaction_id = "plan_#{next_seq}"
+        emit("plan.proposed", { "id" => @plan_interaction_id, "plan" => event.plan.to_s })
+      end
 
-        ev = build_event("turn.completed", {
-          response: response_text,
-          turnCount: event.turn_count,
-          toolCallsMade: event.tool_calls_made,
-          inputTokens: event.input_tokens,
-          outputTokens: event.output_tokens,
-          cost: event.cost
-        })
-        [ev]
+      def plan_approved(event)
+        payload = { "plan" => event.plan.to_s }
+        payload["id"] = @plan_interaction_id if @plan_interaction_id
+        emit("plan.approved", payload)
       end
 
-      def translate_error(event)
-        return [] if @turn_active
-        translate_turn_failed(event.error)
+      def plan_rejected(event)
+        payload = { "plan" => event.plan.to_s }
+        payload["id"] = @plan_interaction_id if @plan_interaction_id
+        emit("plan.rejected", payload)
       end
 
-      def translate_turn_failed(message)
+      def session_end(event)
         @turn_active = false
-        ev = build_event("turn.failed", {
-          error: { message: message.to_s }
-        })
-        [ev]
-      end
-
-      def build_event(type, payload)
-        event = {
-          type: type,
-          seq: next_seq,
-          payload: payload,
-          turnId: @turn_id,
-          sessionId: @session_id
-        }
+        payload = {}
+        payload["turnId"] = @turn_id if @turn_id
+        payload["response"] = event.result.to_s
+        payload["inputTokens"] = event.input_tokens if event.input_tokens
+        payload["outputTokens"] = event.output_tokens if event.output_tokens
+        payload["cost"] = event.cost if event.cost
+        emit("turn.completed", payload)
+      end
+
+      def error(event)
+        payload = { "error" => event.error.to_s }
+        payload["recoverable"] = event.recoverable unless event.recoverable.nil?
+        emit("error", payload)
+      end
+
+      def turn_failed(message)
+        @turn_active = false
+        payload = { "error" => message.to_s }
+        payload["turnId"] = @turn_id if @turn_id
+        emit("turn.failed", payload)
+      end
+
+      def emit(type, payload)
+        event = Ask::SessionProtocol::Events.event(type: type, seq: next_seq, payload: payload)
         @events << event
-        event
+        @events.shift if @events.size > MAX_EVENTS
+        on_event&.call(event)
+        [event]
       end
     end
   end