ask-session-protocol 0.2.0

data/lib/ask/session_protocol/client.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+require "thread"
+
+module Ask
+  module SessionProtocol
+    # A thin client of the canonical Ask::SessionProtocol. Speaks NDJSON
+    # over an input/output pair (the spawned host's stdio, or a unix
+    # socket) and knows nothing else: no runtime, no sessions — the host
+    # owns all of it.
+    #
+    # A reader thread routes incoming messages: responses are matched to
+    # their pending request by id and delivered with a ConditionVariable;
+    # everything else (session/event notifications, reverse requests) is
+    # pushed to a notification queue for the caller to drain.
+    class Client
+      # Raised when a request gets no response in time.
+      class RequestTimeout < StandardError; end
+
+      # Raised when the host closes the connection.
+      class ConnectionClosed < StandardError; end
+
+      # A JSON-RPC error from the host.
+      class ProtocolError < StandardError
+        attr_reader :code
+
+        def initialize(code, message)
+          @code = code
+          super(message)
+        end
+      end
+
+      # Sentinel notification pushed when the host closes the connection,
+      # so waiters on {#wait_notification} unblock.
+      CONNECTION_CLOSED = { "method" => "connection.closed" }.freeze
+
+      # @param input [IO] NDJSON source (host stdout / socket)
+      # @param output [IO] NDJSON sink (host stdin / socket)
+      def initialize(input:, output:)
+        @input = input
+        @output = output
+        @pending = {}
+        @next_id = 1
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @notifications = Queue.new
+        @closed = false
+        @reader = Thread.new { read_loop }
+      end
+
+      # Send a request and wait for its response.
+      #
+      # @param method [String] canonical client → host method
+      # @param params [Hash]
+      # @param timeout [Numeric, nil] seconds to wait; nil waits forever
+      # @return [Hash] the response result
+      # @raise [ProtocolError] on a JSON-RPC error response
+      # @raise [RequestTimeout] when no response arrives in time
+      # @raise [ConnectionClosed] when the host closed the connection
+      def request(method, params = {}, timeout: nil)
+        raise ConnectionClosed, "connection is closed" if @closed
+
+        id = next_id
+        entry = { done: false, result: nil, error: nil }
+        @mutex.synchronize { @pending[id] = entry }
+
+        begin
+          @output.puts(JSON.generate({ id: id, method: method, params: params }))
+          @output.flush
+        rescue Errno::EPIPE, IOError
+          raise ConnectionClosed, "host closed the connection"
+        end
+
+        deadline = timeout && (Time.now + timeout)
+        @mutex.synchronize do
+          until entry[:done]
+            remaining = deadline && (deadline - Time.now)
+            raise RequestTimeout, "#{method} timed out after #{timeout}s" if remaining && remaining <= 0
+
+            @condition.wait(@mutex, remaining || 1)
+          end
+        end
+        raise entry[:error] if entry[:error]
+
+        entry[:result]
+      ensure
+        @mutex.synchronize { @pending.delete(id) } if id
+      end
+
+      # Wait for the next notification (blocking, or with a timeout).
+      # Returns a Hash { "method" =>, "params" => }, or the
+      # {CONNECTION_CLOSED} sentinel when the host disconnected.
+      #
+      # The sentinel is delivered to every waiter: several watchers may
+      # share one connection (the board watches every task of a project
+      # over a single client), and a single queued sentinel would wake
+      # only one of them — the rest would wait on an empty queue
+      # forever, keeping their runs' leases fresh so recovery never
+      # touches them.
+      def wait_notification(timeout: nil)
+        if @closed && @notifications.empty?
+          return CONNECTION_CLOSED
+        end
+
+        return @notifications.pop unless timeout
+
+        Timeout.timeout(timeout) { @notifications.pop }
+      rescue Timeout::Error
+        nil
+      end
+
+      # True when the host connection has closed.
+      def closed?
+        @closed
+      end
+
+      # Close the client: close the sink (which ends the host's stdin,
+      # for spawned hosts) and stop the reader thread.
+      def close
+        @output.close rescue nil
+        @reader&.kill rescue nil
+      end
+
+      # ── Convenience wrappers over the canonical surface ────────────────
+
+      def initialize!(client: { name: "ask-session-protocol", version: Ask::SessionProtocol::VERSION })
+        request("initialize", { client: client })
+      end
+
+      def create_session(workspace_path: nil, mode: nil, model: nil, tools: nil, system_prompt: nil)
+        params = {
+          workspace: { workspacePath: workspace_path },
+          mode: mode,
+          model: model
+        }.compact
+        params[:tools] = tools if tools
+        params[:systemPrompt] = system_prompt if system_prompt
+        request("session/create", params)
+      end
+
+      def subscribe(session_id, after_seq: 0)
+        request("session/subscribe", { sessionId: session_id, afterSeq: after_seq })
+      end
+
+      def send(session_id, content, expected_turn_id: nil)
+        params = { sessionId: session_id, content: content }
+        params[:expectedTurnId] = expected_turn_id if expected_turn_id
+        request("session/send", params)
+      end
+
+      def abort(session_id)
+        request("session/abort", { sessionId: session_id })
+      end
+
+      def close_session(session_id)
+        request("session/close", { sessionId: session_id })
+      end
+
+      def list_interactions(session_id)
+        request("interaction/list", { sessionId: session_id })
+      end
+
+      def approve(session_id, interaction_id)
+        request("interaction/approve", { sessionId: session_id, interactionId: interaction_id })
+      end
+
+      def reject(session_id, interaction_id)
+        request("interaction/reject", { sessionId: session_id, interactionId: interaction_id })
+      end
+
+      def approve_all(session_id)
+        request("interaction/approve-all", { sessionId: session_id })
+      end
+
+      def reject_all(session_id)
+        request("interaction/reject-all", { sessionId: session_id })
+      end
+
+      def plan_approve(session_id)
+        request("plan/approve", { sessionId: session_id })
+      end
+
+      def plan_reject(session_id)
+        request("plan/reject", { sessionId: session_id })
+      end
+
+      def read_workspace_state(session_id = nil)
+        params = session_id ? { sessionId: session_id } : {}
+        request("workspace/readState", params)
+      end
+
+      private
+
+      def next_id
+        @mutex.synchronize do
+          id = @next_id
+          @next_id += 1
+          id
+        end
+      end
+
+      def read_loop
+        while (line = @input.gets)
+          line = line.strip
+          next if line.empty?
+
+          begin
+            msg = JSON.parse(line)
+          rescue JSON::ParserError
+            # Non-protocol noise on the stream (a stray log line); ignore
+            # it — only EOF or I/O errors mean the host is gone.
+            next
+          end
+          if response?(msg)
+            deliver_response(msg)
+          else
+            @notifications << msg
+          end
+        end
+      rescue IOError, SystemCallError
+        # Host went away; fall through to close handling.
+      ensure
+        mark_closed
+      end
+
+      def response?(msg)
+        msg["id"] && !msg.key?("method")
+      end
+
+      def deliver_response(msg)
+        entry = @mutex.synchronize { @pending.delete(msg["id"]) }
+        return unless entry
+
+        entry[:error] = build_error(msg["error"]) if msg["error"]
+        entry[:result] = msg["result"] unless msg["error"]
+        entry[:done] = true
+        @mutex.synchronize { @condition.broadcast }
+      end
+
+      def build_error(error)
+        ProtocolError.new(error["code"], error["message"].to_s)
+      end
+
+      def mark_closed
+        @mutex.synchronize do
+          @closed = true
+          @pending.each_value do |entry|
+            entry[:error] = ConnectionClosed.new("host closed the connection")
+            entry[:done] = true
+          end
+          @pending.clear
+          @condition.broadcast
+        end
+        @notifications << CONNECTION_CLOSED
+      end
+    end
+  end
+end

data/lib/ask/session_protocol/events.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+module Ask
+  module SessionProtocol
+    # The canonical session event vocabulary.
+    #
+    # Every event on the wire has the same envelope:
+    #
+    #   { "type" => "model.streaming", "seq" => 12, "payload" => { "delta" => "..." } }
+    #
+    # * type   — one of the canonical dot-names below (additive growth only;
+    #            clients must tolerate unknown types within a major version)
+    # * seq    — monotonically increasing per session; clients use it for
+    #            ordering, dedup, and replay (ask "events after seq N")
+    # * payload — the event body, string-keyed
+    #
+    # Events marked `interaction` (approval.required, plan.proposed) are
+    # resolvable by id from ANY client through the interaction/* and
+    # plan/* methods — a terminal, web console, or bot resolves the same
+    # pending interaction, and the host tombstones delivery per subscriber.
+    module Events
+      # Payload field types accepted by the validator.
+      FIELD_TYPES = %i[string integer number boolean object array any].freeze
+
+      # The canonical event registry. Each entry describes the event and the
+      # shape of its payload. This registry is the single source of truth
+      # for the event vocabulary — the JSON Schema artifact is generated
+      # from it, and hosts/clients validate against it.
+      TYPES = {
+        # ── Session lifecycle ────────────────────────────────────────────
+        "session.created" => {
+          description: "A session was created and is ready to receive prompts.",
+          interaction: false,
+          payload: {
+            "sessionId" => { type: :string, required: true, description: "The session identifier." }
+          }
+        },
+        "session.ended" => {
+          description: "The session was closed and its resources released.",
+          interaction: false,
+          payload: {
+            "sessionId" => { type: :string, required: true, description: "The session identifier." },
+            "reason" => { type: :string, required: false, description: "Why the session ended: closed, aborted, error, ..." }
+          }
+        },
+
+        # ── Turn lifecycle ───────────────────────────────────────────────
+        "turn.started" => {
+          description: "A turn (prompt → response → tool loop) began.",
+          interaction: false,
+          payload: {
+            "turnId" => { type: :string, required: true, description: "Identifies the turn; correlates all of its events." }
+          }
+        },
+        "turn.completed" => {
+          description: "A turn finished successfully. The accumulated response text is in `response`.",
+          interaction: false,
+          payload: {
+            "turnId" => { type: :string, required: true, description: "The turn identifier." },
+            "response" => { type: :string, required: false, description: "Final assistant text for the turn." },
+            "inputTokens" => { type: :integer, required: false, description: "LLM input tokens used in the turn." },
+            "outputTokens" => { type: :integer, required: false, description: "LLM output tokens used in the turn." },
+            "cost" => { type: :number, required: false, description: "Estimated cost of the turn in USD." }
+          }
+        },
+        "turn.failed" => {
+          description: "A turn failed; the session remains usable.",
+          interaction: false,
+          payload: {
+            "turnId" => { type: :string, required: true, description: "The turn identifier." },
+            "error" => { type: :string, required: true, description: "Human-readable failure reason." }
+          }
+        },
+        "turn.aborted" => {
+          description: "A turn was aborted by the user (session/abort) or the host.",
+          interaction: false,
+          payload: {
+            "turnId" => { type: :string, required: true, description: "The turn identifier." }
+          }
+        },
+
+        # ── Model output ─────────────────────────────────────────────────
+        "model.streaming" => {
+          description: "A delta of the assistant's response text.",
+          interaction: false,
+          payload: {
+            "delta" => { type: :string, required: true, description: "The next chunk of text." }
+          }
+        },
+        "model.thinking" => {
+          description: "A delta of the model's reasoning/thinking text (rendered collapsibly).",
+          interaction: false,
+          payload: {
+            "delta" => { type: :string, required: true, description: "The next chunk of thinking text." }
+          }
+        },
+
+        # ── Tool execution ───────────────────────────────────────────────
+        "tool.use" => {
+          description: "The model requested a tool call; execution is about to start.",
+          interaction: false,
+          payload: {
+            "id" => { type: :string, required: true, description: "Tool call identifier; correlates use/delta/result." },
+            "name" => { type: :string, required: true, description: "Tool name, e.g. bash, write." },
+            "args" => { type: :any, required: false, description: "Tool arguments (object or pre-serialized string)." }
+          }
+        },
+        "tool.delta" => {
+          description: "A partial result while a tool is executing.",
+          interaction: false,
+          payload: {
+            "id" => { type: :string, required: true, description: "Tool call identifier." },
+            "name" => { type: :string, required: true, description: "Tool name." },
+            "partial" => { type: :string, required: true, description: "The next chunk of tool output." }
+          }
+        },
+        "tool.result" => {
+          description: "A tool finished executing.",
+          interaction: false,
+          payload: {
+            "id" => { type: :string, required: true, description: "Tool call identifier." },
+            "name" => { type: :string, required: true, description: "Tool name." },
+            "output" => { type: :any, required: false, description: "Tool output (string or structured value)." },
+            "isError" => { type: :boolean, required: false, description: "True when the tool failed." },
+            "durationMs" => { type: :integer, required: false, description: "Execution duration in milliseconds." }
+          }
+        },
+
+        # ── Interactions (resolvable by id from any client) ─────────────
+        "approval.required" => {
+          description: "A tool is queued for human approval. Resolve via interaction/approve or interaction/reject.",
+          interaction: true,
+          payload: {
+            "id" => { type: :string, required: true, description: "Interaction id; used to resolve this request." },
+            "toolName" => { type: :string, required: true, description: "The tool waiting for approval." },
+            "args" => { type: :any, required: false, description: "Tool arguments under review." },
+            "message" => { type: :string, required: false, description: "Reason the approval was requested." },
+            "autoApprovable" => { type: :boolean, required: false, description: "True when a configured rule may auto-approve." }
+          }
+        },
+        "approval.updated" => {
+          description: "A pending approval was resolved.",
+          interaction: false,
+          payload: {
+            "id" => { type: :string, required: true, description: "The interaction id from approval.required." },
+            "status" => { type: :string, required: true, enum: %w[approved rejected], description: "How it was resolved." }
+          }
+        },
+        "plan.proposed" => {
+          description: "The agent proposed a plan (plan mode). Resolve via plan/approve or plan/reject.",
+          interaction: true,
+          payload: {
+            "id" => { type: :string, required: true, description: "Interaction id; used to resolve this proposal." },
+            "plan" => { type: :string, required: true, description: "The proposed plan text." }
+          }
+        },
+        "plan.approved" => {
+          description: "A proposed plan was approved and the agent may proceed.",
+          interaction: false,
+          payload: {
+            "id" => { type: :string, required: false, description: "The interaction id from plan.proposed, when known." },
+            "plan" => { type: :string, required: true, description: "The approved plan text." }
+          }
+        },
+        "plan.rejected" => {
+          description: "A proposed plan was rejected; the agent stays in plan mode.",
+          interaction: false,
+          payload: {
+            "id" => { type: :string, required: false, description: "The interaction id from plan.proposed, when known." },
+            "plan" => { type: :string, required: true, description: "The rejected plan text." }
+          }
+        },
+
+        # ── Session state ────────────────────────────────────────────────
+        "todos.updated" => {
+          description: "The session's todo list changed. Payload carries the full list.",
+          interaction: false,
+          payload: {
+            "todos" => { type: :array, required: true, description: "Full todo list: [{id, title, status}]." }
+          }
+        },
+        "file.changed" => {
+          description: "A file in the workspace changed (create/modify/delete).",
+          interaction: false,
+          payload: {
+            "path" => { type: :string, required: true, description: "Workspace-relative file path." },
+            "type" => { type: :string, required: true, enum: %w[created modified deleted], description: "Kind of change." },
+            "patch" => { type: :string, required: false, description: "Unified diff text for created/modified files." }
+          }
+        },
+
+        # ── Errors ───────────────────────────────────────────────────────
+        "error" => {
+          description: "A non-fatal error was emitted outside a turn (recoverable when flagged).",
+          interaction: false,
+          payload: {
+            "error" => { type: :string, required: true, description: "Error message." },
+            "recoverable" => { type: :boolean, required: false, description: "True when the host can continue." }
+          }
+        }
+      }.freeze
+
+      # ── Envelope ───────────────────────────────────────────────────────
+
+      # An event on the wire. Immutable; validate on construction.
+      Event = Data.define(:type, :seq, :payload) do
+        # @param type [String] canonical event type (see Events::TYPES)
+        # @param seq [Integer] monotonic per-session sequence number (> 0)
+        # @param payload [Hash] string-keyed event body
+        def initialize(type:, seq:, payload: {})
+          unless Events.known?(type)
+            raise ArgumentError, "unknown session event type: #{type.inspect}"
+          end
+          unless seq.is_a?(Integer) && seq.positive?
+            raise ArgumentError, "event seq must be a positive integer, got: #{seq.inspect}"
+          end
+          raise ArgumentError, "event payload must be a Hash, got: #{payload.class}" unless payload.is_a?(Hash)
+
+          super(type: type, seq: seq, payload: payload.freeze)
+        end
+
+        # Wire shape: { "type" => ..., "seq" => ..., "payload" => ... }
+        def to_h
+          { "type" => type, "seq" => seq, "payload" => payload }
+        end
+      end
+
+      # Build and validate an event.
+      #
+      # @param type [String] canonical event type
+      # @param seq [Integer] monotonic per-session sequence number
+      # @param payload [Hash] event body; validated against the registry
+      # @return [Event]
+      def self.event(type:, seq:, payload: {})
+        validate_payload!(type, payload)
+        Event.new(type: type, seq: seq, payload: payload)
+      end
+
+      # Rebuild an event from its wire shape, validating as it goes.
+      #
+      # @param hash [Hash] { "type" =>, "seq" =>, "payload" => }
+      # @return [Event]
+      def self.from_h(hash)
+        hash = hash.transform_keys(&:to_s)
+        raise ArgumentError, "event must be a Hash" unless hash.is_a?(Hash)
+        raise ArgumentError, "event missing type" if hash["type"].nil?
+        raise ArgumentError, "event missing seq" if hash["seq"].nil?
+
+        payload = hash["payload"] || {}
+        event(type: hash["type"], seq: hash["seq"], payload: payload)
+      end
+
+      # Whether `type` is a canonical event type.
+      def self.known?(type)
+        TYPES.key?(type)
+      end
+
+      # Whether an event type is a resolvable interaction.
+      def self.interaction?(type)
+        spec = TYPES[type]
+        spec && spec[:interaction]
+      end
+
+      # The canonical event types, in registry order.
+      def self.types
+        TYPES.keys
+      end
+
+      # Validate a payload against the registry spec for `type`.
+      # Raises ArgumentError on unknown types, missing required fields, or
+      # type/enum mismatches. Unknown extra fields are allowed (forward
+      # compatibility within a major protocol version).
+      #
+      # @param type [String] canonical event type
+      # @param payload [Hash] event body
+      # @return [true] when valid
+      def self.validate_payload!(type, payload)
+        spec = TYPES[type]
+        raise ArgumentError, "unknown session event type: #{type.inspect}" unless spec
+        raise ArgumentError, "payload for #{type} must be a Hash" unless payload.is_a?(Hash)
+
+        spec[:payload].each do |field, field_spec|
+          value = payload[field]
+          if field_spec[:required] && value.nil?
+            raise ArgumentError, "event #{type} missing required payload field #{field.inspect}"
+          end
+          next if value.nil?
+
+          validate_field!(type, field, field_spec, value)
+        end
+        true
+      end
+
+      # Shared field validator, used by the events, interactions, and
+      # methods registries. Public because sibling modules call it with an
+      # explicit receiver.
+      #
+      # @api private
+      def self.validate_field!(type, field, field_spec, value)
+        kind = field_spec[:type]
+        ok =
+          case kind
+          when :any then true
+          when :string then value.is_a?(String)
+          when :integer then value.is_a?(Integer)
+          when :number then value.is_a?(Numeric)
+          when :boolean then value == true || value == false
+          when :object then value.is_a?(Hash)
+          when :array then value.is_a?(Array)
+          end
+        unless ok
+          raise ArgumentError, "event #{type} field #{field.inspect} must be a #{kind}, got #{value.class}"
+        end
+
+        if field_spec[:enum] && !field_spec[:enum].include?(value)
+          raise ArgumentError,
+                "event #{type} field #{field.inspect} must be one of #{field_spec[:enum].inspect}, got #{value.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/ask/session_protocol/host.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Ask
+  module SessionProtocol
+    # How the terminal client reaches a session host.
+    #
+    #   spawn   — launch ask-app-server as a subprocess (stdio transport)
+    #             with a unix socket for multi-client attach; the
+    #             "embedded" mode: one host process owned by this client
+    #   connect — attach to an already-running host over its unix socket
+    #             (multi-client mode: web console, bots, and this terminal
+    #             share the same live sessions)
+    module Host
+      # A spawned host subprocess.
+      SpawnResult = Data.define(:client, :stderr, :process, :socket_path) do
+        # Close the client and reap the subprocess.
+        def close
+          client.close
+          stderr.close rescue nil
+          process&.wait rescue nil
+        end
+      end
+
+      # Spawn ask-app-server as a subprocess and return a Client over its
+      # stdio. By default the host also exposes a unix socket (unique per
+      # spawn under ~/.ask-app-server/sockets/) so other clients — the web
+      # console, bots, a second terminal — can attach to the same live
+      # sessions; the path is available on the result.
+      #
+      # @param command [String, nil] host command (defaults to the
+      #   ask-app-server gem's executable, falling back to PATH)
+      # @param args [Array<String>] extra host arguments
+      # @param socket [Boolean, String, nil] true (default) spawns with a
+      #   generated unique socket; a String uses that exact path; false
+      #   disables the socket entirely
+      # @param env [Hash{String => String}] extra environment for the host
+      #   process (e.g. ASK_APP_SERVER_PRELOAD for executor tools)
+      # @return [SpawnResult]
+      def self.spawn(command: nil, args: [], socket: true, env: {})
+        require "open3"
+        command ||= begin
+          Gem.bin_path("ask-app-server", "ask-app-server")
+        rescue Gem::Exception
+          "ask-app-server"
+        end
+
+        socket_path = resolve_socket_path(socket)
+        spawn_args = args.dup
+        spawn_args += ["--socket", socket_path] if socket_path
+
+        stdin, stdout, stderr, wait_thread = Open3.popen3(env, command, *spawn_args)
+        client = Client.new(input: stdout, output: stdin)
+        SpawnResult.new(client: client, stderr: stderr, process: wait_thread, socket_path: socket_path)
+      end
+
+      # Attach to an existing host over its unix socket.
+      #
+      # @param socket_path [String] host socket (printed by `ask` on spawn)
+      # @return [Client]
+      def self.connect(socket_path)
+        require "socket"
+        socket = UNIXSocket.new(socket_path)
+        Client.new(input: socket, output: socket)
+      end
+
+      # @api private
+      def self.resolve_socket_path(socket)
+        return nil if socket == false || socket.nil?
+        return socket if socket.is_a?(String)
+
+        # Explicit env wins; otherwise a unique path per spawn so
+        # concurrent hosts never fight over the same socket.
+        ENV["ASK_APP_SERVER_SOCKET"] ||
+          File.join(Dir.home, ".ask-app-server", "sockets", "#{SecureRandom.hex(8)}.sock")
+      end
+      private_class_method :resolve_socket_path
+    end
+  end
+end