ask-session-protocol 0.2.0

data/lib/ask/session_protocol/interactions.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Ask
+  module SessionProtocol
+    # Resolvable interactions — the human-in-the-loop surface of the
+    # protocol.
+    #
+    # An interaction is created by the host (emitted as an interaction
+    # event: approval.required, plan.proposed) with a unique id. Any client
+    # may resolve it by id through the interaction/* and plan/* methods;
+    # the host routes the resolution to the session and tombstones delivery
+    # so each subscriber sees it exactly once.
+    #
+    #   approval.required ──▶ interaction/approve | interaction/reject
+    #   plan.proposed     ──▶ plan/approve        | plan/reject
+    #   user input        ──▶ interaction/respond  (host → client request)
+    module Interactions
+      # The interaction kinds.
+      KINDS = %w[approval plan user_input].freeze
+
+      # Resolution statuses. A resolved interaction never returns to pending.
+      STATUSES = %w[pending approved rejected responded expired].freeze
+
+      # An interaction on the wire. Immutable.
+      #
+      #   { "id" => "act_123", "kind" => "approval",
+      #     "status" => "pending", "payload" => { "toolName" => "bash", ... } }
+      Interaction = Data.define(:id, :kind, :status, :payload) do
+        def initialize(id:, kind:, status: "pending", payload: {})
+          unless id.is_a?(String) && !id.empty?
+            raise ArgumentError, "interaction id must be a non-empty String"
+          end
+          unless KINDS.include?(kind)
+            raise ArgumentError, "unknown interaction kind: #{kind.inspect} (expected one of #{KINDS.inspect})"
+          end
+          unless STATUSES.include?(status)
+            raise ArgumentError, "unknown interaction status: #{status.inspect} (expected one of #{STATUSES.inspect})"
+          end
+          raise ArgumentError, "interaction payload must be a Hash" unless payload.is_a?(Hash)
+
+          super
+        end
+
+        def pending?
+          status == "pending"
+        end
+
+        def resolved?
+          status != "pending"
+        end
+
+        def to_h
+          { "id" => id, "kind" => kind, "status" => status, "payload" => payload }
+        end
+      end
+
+      # ── Kind payload shapes ────────────────────────────────────────────
+
+      # Payload shape for kind "approval" (from the approval.required event).
+      APPROVAL_PAYLOAD = {
+        "toolName" => { type: :string, required: true },
+        "args" => { type: :any, required: false },
+        "message" => { type: :string, required: false },
+        "autoApprovable" => { type: :boolean, required: false }
+      }.freeze
+
+      # Payload shape for kind "plan" (from the plan.proposed event).
+      PLAN_PAYLOAD = {
+        "plan" => { type: :string, required: true }
+      }.freeze
+
+      # Payload shape for kind "user_input" (host → client request asking
+      # the human for input; resolve via interaction/respond).
+      USER_INPUT_PAYLOAD = {
+        "prompt" => { type: :string, required: true, description: "What the agent is asking the human." },
+        "options" => { type: :array, required: false, description: "Suggested answers, when the host offers any." }
+      }.freeze
+
+      # Payload spec per kind. The single source of truth for interaction
+      # payload validation and schema generation.
+      PAYLOADS = {
+        "approval" => APPROVAL_PAYLOAD,
+        "plan" => PLAN_PAYLOAD,
+        "user_input" => USER_INPUT_PAYLOAD
+      }.freeze
+
+      # Build an interaction, validating the payload against its kind.
+      #
+      # @param id [String] unique interaction id
+      # @param kind [String] one of KINDS
+      # @param status [String] one of STATUSES
+      # @param payload [Hash] kind-specific body
+      # @return [Interaction]
+      def self.interaction(id:, kind:, status: "pending", payload: {})
+        validate_payload!(kind, payload)
+        Interaction.new(id: id, kind: kind, status: status, payload: payload)
+      end
+
+      # Rebuild an interaction from its wire shape.
+      #
+      # @param hash [Hash] { "id" =>, "kind" =>, "status" =>, "payload" => }
+      # @return [Interaction]
+      def self.from_h(hash)
+        hash = hash.transform_keys(&:to_s)
+        raise ArgumentError, "interaction must be a Hash" unless hash.is_a?(Hash)
+
+        interaction(
+          id: hash["id"],
+          kind: hash["kind"],
+          status: hash["status"] || "pending",
+          payload: hash["payload"] || {}
+        )
+      end
+
+      # Validate a payload against its kind spec. Unknown extra fields are
+      # allowed (forward compatibility).
+      #
+      # @param kind [String] one of KINDS
+      # @param payload [Hash]
+      # @return [true] when valid
+      def self.validate_payload!(kind, payload)
+        spec = PAYLOADS[kind]
+        raise ArgumentError, "unknown interaction kind: #{kind.inspect}" unless spec
+        raise ArgumentError, "payload for #{kind} must be a Hash" unless payload.is_a?(Hash)
+
+        spec.each do |field, field_spec|
+          value = payload[field]
+          if field_spec[:required] && value.nil?
+            raise ArgumentError, "interaction #{kind} missing required payload field #{field.inspect}"
+          end
+          next if value.nil?
+
+          Events.validate_field!(kind, field, field_spec, value)
+        end
+        true
+      end
+    end
+  end
+end

data/lib/ask/session_protocol/methods.rb

@@ -0,0 +1,393 @@
+# frozen_string_literal: true
+
+module Ask
+  module SessionProtocol
+    # The RPC surface of the session protocol.
+    #
+    # Direction conventions (JSON-RPC 2.0 over the host's transport):
+    #
+    #   METHODS       — client → host requests (host responds with a result)
+    #   NOTIFICATIONS — host → client notifications (no response expected):
+    #                   session/event carries the canonical event envelope
+    #   REQUESTS      — host → client reverse requests (client must respond):
+    #                   interaction/requestPermission and
+    #                   interaction/requestUserInput, defined for interop
+    #                   with the external app-server protocol standard.
+    #                   The canonical resolution path is the interaction/*
+    #                   and plan/* METHODS against event-visible interactions.
+    #
+    # The registry below is the single source of truth for the method
+    # surface; the JSON Schema artifact is generated from it, and hosts
+    # and clients validate their implementations against it.
+    module Methods
+      # Host capabilities advertised in the `initialize` result. A client
+      # may gate UI features on them.
+      CAPABILITIES = %w[
+        sessionManagement eventStreaming midExecutionInjection
+        interactions planMode todos artifacts workspace fileEvents
+      ].freeze
+
+      # Error codes, JSON-RPC 2.0 reserved range plus session/interaction
+      # application codes (matching the app-server protocol convention).
+      ERROR_CODES = {
+        parse_error: -32700,
+        invalid_request: -32600,
+        method_not_found: -32601,
+        invalid_params: -32602,
+        internal_error: -32603,
+        session_not_found: -32004,
+        session_already_exists: -32005,
+        interaction_not_found: -32006,
+        plan_not_found: -32007,
+        workspace_error: -32008,
+        not_implemented: -32009
+      }.freeze
+
+      # Client → host methods with their params and result shapes. Each
+      # shape uses the same field-spec language as Events::TYPES.
+      METHODS = {
+        # ── Handshake ───────────────────────────────────────────────────
+        "ping" => {
+          description: "Liveness check.",
+          params: {},
+          result: {
+            "status" => { type: :string, required: true },
+            "version" => { type: :string, required: true, description: "Gem/host version." },
+            "protocolVersion" => { type: :string, required: true, description: "Negotiated wire version." },
+            "uptime" => { type: :integer, required: false, description: "Host uptime in seconds." },
+            "sessions" => { type: :integer, required: false, description: "Live session count." }
+          }
+        },
+        "initialize" => {
+          description: "Handshake: negotiate protocol version and exchange capabilities.",
+          params: {
+            "client" => { type: :object, required: false, description: "{name, version} of the client." },
+            "capabilities" => { type: :array, required: false, description: "Client capabilities (informational)." }
+          },
+          result: {
+            "protocolVersion" => { type: :string, required: true },
+            "capabilities" => { type: :array, required: true, description: "Host capabilities (see CAPABILITIES)." },
+            "server" => { type: :object, required: true, description: "{name, version} of the host." }
+          }
+        },
+
+        # ── Session lifecycle ────────────────────────────────────────────
+        "session/create" => {
+          description: "Create a session in a workspace.",
+          params: {
+            "workspace" => { type: :object, required: false, description: "{workspacePath} of the project." },
+            "mode" => { type: :string, required: false, description: "Permission mode, e.g. on_request, full_access." },
+            "model" => { type: :string, required: false, description: "Model identifier." },
+            "tools" => { type: :array, required: false, description: "Tool names to enable." },
+            "systemPrompt" => { type: :string, required: false, description: "System prompt override." }
+          },
+          result: {
+            "session" => { type: :object, required: true, description: "{sessionId, model, createdAt}." }
+          }
+        },
+        "session/list" => {
+          description: "List sessions, most recent first.",
+          params: {
+            "limit" => { type: :integer, required: false, description: "Max sessions (default 20)." }
+          },
+          result: {
+            "sessions" => { type: :array, required: true, description: "Session summaries." }
+          }
+        },
+        "session/resume" => {
+          description: "Resume/attach to an existing session.",
+          params: {
+            "sessionId" => { type: :string, required: true }
+          },
+          result: {
+            "sessionId" => { type: :string, required: true },
+            "running" => { type: :boolean, required: true, description: "A turn is in progress." },
+            "idle" => { type: :boolean, required: true, description: "The session is ready for a prompt." },
+            "createdAt" => { type: :string, required: true, description: "ISO 8601 creation time." }
+          }
+        },
+        "session/subscribe" => {
+          description: "Subscribe to a session's event stream with replay support.",
+          params: {
+            "sessionId" => { type: :string, required: true },
+            "deliveryKind" => { type: :string, required: false, enum: DELIVERY_KINDS, description: "Default: replay." },
+            "afterSeq" => { type: :integer, required: false, description: "Replay events after this seq." },
+            "includeSnapshot" => { type: :boolean, required: false, description: "Include a state snapshot in the result." }
+          },
+          result: {
+            "subscription" => { type: :object, required: true, description: "{sessionId, deliveryKind}." },
+            "snapshot" => { type: :array, required: false, description: "Events after afterSeq, when includeSnapshot." }
+          }
+        },
+        "session/events" => {
+          description: "Poll events after a seq (for clients without a subscription).",
+          params: {
+            "sessionId" => { type: :string, required: true },
+            "afterSeq" => { type: :integer, required: false, description: "Default 0." },
+            "limit" => { type: :integer, required: false, description: "Max events to return." }
+          },
+          result: {
+            "events" => { type: :array, required: true, description: "Canonical event envelopes." }
+          }
+        },
+        "session/send" => {
+          description: "Inject a message mid-run (barge-in) or prompt an idle session.",
+          params: {
+            "sessionId" => { type: :string, required: true },
+            "content" => { type: :string, required: true, description: "The message text." },
+            "expectedTurnId" => { type: :string, required: false, description: "Staleness guard: only steer this turn." }
+          },
+          result: {
+            "accepted" => { type: :boolean, required: true },
+            "status" => { type: :string, required: false, enum: %w[queued steered stale], description: "steered: injected now; queued: next turn; stale: turn mismatch." },
+            "turnId" => { type: :string, required: false, description: "The turn the message applies to." }
+          }
+        },
+        "session/abort" => {
+          description: "Abort the running turn.",
+          params: {
+            "sessionId" => { type: :string, required: true }
+          },
+          result: {
+            "aborted" => { type: :boolean, required: true },
+            "sessionId" => { type: :string, required: true }
+          }
+        },
+        "session/close" => {
+          description: "Close the session and release its resources.",
+          params: {
+            "sessionId" => { type: :string, required: true }
+          },
+          result: {
+            "closed" => { type: :boolean, required: true },
+            "sessionId" => { type: :string, required: true }
+          }
+        },
+
+        # ── Artifacts ────────────────────────────────────────────────────
+        "session/artifacts" => {
+          description: "List the session's tool artifacts.",
+          params: {
+            "sessionId" => { type: :string, required: true }
+          },
+          result: {
+            "artifacts" => { type: :array, required: true, description: "Artifact summaries." }
+          }
+        },
+        "session/artifact/get" => {
+          description: "Fetch one artifact's content.",
+          params: {
+            "sessionId" => { type: :string, required: true },
+            "artifactId" => { type: :string, required: true }
+          },
+          result: {
+            "artifact" => { type: :object, required: true, description: "Artifact record with content or uri." }
+          }
+        },
+
+        # ── Interactions (approval, user input) ──────────────────────────
+        "interaction/list" => {
+          description: "List pending interactions for a session.",
+          params: {
+            "sessionId" => { type: :string, required: true }
+          },
+          result: {
+            "interactions" => { type: :array, required: true, description: "Pending interaction records." }
+          }
+        },
+        "interaction/approve" => {
+          description: "Approve a pending interaction by id (approval.required).",
+          params: {
+            "sessionId" => { type: :string, required: true },
+            "interactionId" => { type: :string, required: true }
+          },
+          result: {
+            "approved" => { type: :boolean, required: true },
+            "interactionId" => { type: :string, required: true }
+          }
+        },
+        "interaction/reject" => {
+          description: "Reject a pending interaction by id (approval.required).",
+          params: {
+            "sessionId" => { type: :string, required: true },
+            "interactionId" => { type: :string, required: true }
+          },
+          result: {
+            "rejected" => { type: :boolean, required: true },
+            "interactionId" => { type: :string, required: true }
+          }
+        },
+        "interaction/approve-all" => {
+          description: "Approve every pending approval interaction.",
+          params: {
+            "sessionId" => { type: :string, required: true }
+          },
+          result: {
+            "approved" => { type: :integer, required: true, description: "Number approved." }
+          }
+        },
+        "interaction/reject-all" => {
+          description: "Reject every pending approval interaction.",
+          params: {
+            "sessionId" => { type: :string, required: true }
+          },
+          result: {
+            "rejected" => { type: :integer, required: true, description: "Number rejected." }
+          }
+        },
+        "interaction/respond" => {
+          description: "Answer a user_input interaction by id (elicitation).",
+          params: {
+            "sessionId" => { type: :string, required: true },
+            "interactionId" => { type: :string, required: true },
+            "response" => { type: :string, required: true }
+          },
+          result: {
+            "responded" => { type: :boolean, required: true },
+            "interactionId" => { type: :string, required: true }
+          }
+        },
+
+        # ── Plan mode ────────────────────────────────────────────────────
+        "plan/approve" => {
+          description: "Approve the pending plan proposal (plan.proposed).",
+          params: {
+            "sessionId" => { type: :string, required: true }
+          },
+          result: {
+            "approved" => { type: :boolean, required: true }
+          }
+        },
+        "plan/reject" => {
+          description: "Reject the pending plan proposal; the agent stays in plan mode.",
+          params: {
+            "sessionId" => { type: :string, required: true }
+          },
+          result: {
+            "rejected" => { type: :boolean, required: true }
+          }
+        },
+
+        # ── Workspace ────────────────────────────────────────────────────
+        "workspace/readState" => {
+          description: "Read the host's workspace state (path, git, mode).",
+          params: {},
+          result: {
+            "workspace" => { type: :object, required: true, description: "{path, name, gitBranch, mode}." }
+          }
+        }
+      }.freeze
+
+      # Host → client notifications (fire-and-forget).
+      NOTIFICATIONS = {
+        "session/event" => {
+          description: "A canonical session event envelope: {type, seq, payload}.",
+          params: {
+            "event" => { type: :object, required: true, description: "The canonical event envelope." }
+          }
+        }
+      }.freeze
+
+      # Host → client reverse requests (client must respond) — defined for
+      # interop with the external app-server protocol standard. The
+      # canonical resolution path is the interaction/* methods.
+      REQUESTS = {
+        "interaction/requestPermission" => {
+          description: "Ask the client to resolve a tool approval (app-server interop).",
+          params: {
+            "requestId" => { type: :string, required: true },
+            "toolName" => { type: :string, required: true },
+            "input" => { type: :any, required: false },
+            "riskLevel" => { type: :string, required: false, enum: %w[low medium high critical] },
+            "reason" => { type: :string, required: false }
+          },
+          result: {
+            "decision" => { type: :string, required: true, enum: %w[allow deny] }
+          }
+        },
+        "interaction/requestUserInput" => {
+          description: "Ask the client for free-form user input (app-server interop).",
+          params: {
+            "requestId" => { type: :string, required: true },
+            "prompt" => { type: :string, required: true },
+            "options" => { type: :array, required: false }
+          },
+          result: {
+            "response" => { type: :string, required: true }
+          }
+        }
+      }.freeze
+
+      class << self
+        # The client → host method names, in registry order.
+        def method_names
+          METHODS.keys
+        end
+
+        # Whether `name` is a canonical client → host method.
+        def known?(name)
+          METHODS.key?(name)
+        end
+
+        # Whether `name` is a host → client notification.
+        def notification?(name)
+          NOTIFICATIONS.key?(name)
+        end
+
+        # Whether `name` is a host → client reverse request.
+        def request?(name)
+          REQUESTS.key?(name)
+        end
+
+        # All method-like names across the three surfaces.
+        def all_names
+          METHODS.keys + NOTIFICATIONS.keys + REQUESTS.keys
+        end
+
+        # Validate a params hash against a method's params spec.
+        # Raises ArgumentError on unknown methods, missing required fields,
+        # or type/enum mismatches. Unknown extra fields are allowed.
+        #
+        # @param name [String] client → host method name
+        # @param params [Hash]
+        # @return [true] when valid
+        def validate_params!(name, params)
+          spec = METHODS[name]
+          raise ArgumentError, "unknown session protocol method: #{name.inspect}" unless spec
+          raise ArgumentError, "params for #{name} must be a Hash" unless params.is_a?(Hash)
+
+          validate_shape!(name, spec[:params], params)
+          true
+        end
+
+        # Validate a result hash against a method's result spec.
+        #
+        # @param name [String] client → host method name
+        # @param result [Hash]
+        # @return [true] when valid
+        def validate_result!(name, result)
+          spec = METHODS[name]
+          raise ArgumentError, "unknown session protocol method: #{name.inspect}" unless spec
+          raise ArgumentError, "result for #{name} must be a Hash" unless result.is_a?(Hash)
+
+          validate_shape!(name, spec[:result], result)
+          true
+        end
+
+        # @api private
+        def validate_shape!(name, shape, value)
+          shape.each do |field, field_spec|
+            field_value = value[field]
+            if field_spec[:required] && field_value.nil?
+              raise ArgumentError, "method #{name} missing required field #{field.inspect}"
+            end
+            next if field_value.nil?
+
+            Events.validate_field!(name, field, field_spec, field_value)
+          end
+        end
+        private :validate_shape!
+      end
+    end
+  end
+end

data/lib/ask/session_protocol/schema.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Ask
+  module SessionProtocol
+    # Generates a JSON Schema (draft 2020-12) document from the contract
+    # registries (Events::TYPES, Interactions::PAYLOADS, Methods::METHODS).
+    #
+    # The output is a static artifact (docs/ask-session-protocol.schema.json,
+    # regenerated by `rake schema`) so non-Ruby clients — bots, IDEs —
+    # can validate against the contract without loading this gem.
+    module Schema
+      # @return [Hash] the JSON Schema document
+      def self.build
+        {
+          "$schema" => "https://json-schema.org/draft/2020-12/schema",
+          "title" => "Ask Session Protocol",
+          "description" => "Canonical wire contract for ask agent sessions: " \
+                           "event vocabulary, interactions, and the RPC method surface. " \
+                           "See the ask-session-protocol gem for the authoritative registry.",
+          "protocolVersion" => Ask::SessionProtocol::PROTOCOL_VERSION,
+          "$defs" => {
+            "event" => build_event_schema,
+            "interaction" => build_interaction_schema,
+            "method" => build_method_schema
+          }
+        }
+      end
+
+      # Convert a registry field spec to a JSON Schema fragment.
+      #
+      # @param field_spec [Hash] { type:, required:, enum:, description: }
+      # @return [Hash]
+      def self.field_schema(field_spec)
+        schema = {}
+        schema["description"] = field_spec[:description] if field_spec[:description]
+        schema["enum"] = field_spec[:enum] if field_spec[:enum]
+
+        case field_spec[:type]
+        when :any then schema
+        when :number then schema.merge("type" => "number")
+        when :object then schema.merge("type" => "object")
+        when :array then schema.merge("type" => "array")
+        else schema.merge("type" => field_spec[:type].to_s)
+        end
+      end
+
+      # Event envelope schema: one schema per canonical event type.
+      #
+      # @return [Hash] "$defs/event"
+      def self.build_event_schema
+        Events::TYPES.each_with_object({}) do |(type, spec), out|
+          out[type] = {
+            "type" => "object",
+            "description" => spec[:description],
+            "properties" => {
+              "type" => { "const" => type },
+              "seq" => { "type" => "integer", "minimum" => 1 },
+              "payload" => build_payload_schema(spec[:payload])
+            },
+            "required" => %w[type seq payload],
+            "additionalProperties" => false
+          }
+          out[type]["x-interaction"] = true if spec[:interaction]
+        end
+      end
+
+      # Interaction schema per kind.
+      #
+      # @return [Hash] "$defs/interaction"
+      def self.build_interaction_schema
+        Interactions::PAYLOADS.each_with_object({}) do |(kind, payload), out|
+          out[kind] = {
+            "type" => "object",
+            "properties" => {
+              "id" => { "type" => "string" },
+              "kind" => { "const" => kind },
+              "status" => { "type" => "string", "enum" => Interactions::STATUSES },
+              "payload" => build_payload_schema(payload)
+            },
+            "required" => %w[id kind status payload],
+            "additionalProperties" => false
+          }
+        end
+      end
+
+      # Method schema per client → host method: params and result.
+      #
+      # @return [Hash] "$defs/method"
+      def self.build_method_schema
+        Methods::METHODS.each_with_object({}) do |(name, spec), out|
+          out[name] = {
+            "type" => "object",
+            "description" => spec[:description],
+            "properties" => {
+              "method" => { "const" => name },
+              "params" => build_payload_schema(spec[:params])
+            },
+            "required" => %w[method params],
+            "additionalProperties" => false
+          }
+        end
+      end
+
+      # @api private
+      def self.build_payload_schema(fields)
+        properties = fields.each_with_object({}) do |(field, field_spec), out|
+          out[field] = field_schema(field_spec)
+        end
+        required = fields.select { |_field, spec| spec[:required] }.keys
+        schema = { "type" => "object", "properties" => properties }
+        schema["required"] = required unless required.empty?
+        schema
+      end
+      private_class_method :build_payload_schema
+    end
+  end
+end

data/lib/ask/session_protocol/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module SessionProtocol
+    VERSION = "0.2.0"
+  end
+end