ask-session-protocol 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 22436fe459ec2c7e91ed8d5c12db05a72d01daaa83794536882d094b084b9b08
+  data.tar.gz: d512c1dea2ebdfbce2ba971d00d4430431b020ee79911fc26585d3ff2aefe0e9
+SHA512:
+  metadata.gz: a4f4a7094797aa9acb3293ef0ab96b69dcdc238b93ed378f32090327605931780cfb3a7c96bdca45d4466fe6b2ba3d90214be360eb03204aa4480b3b93b85eca
+  data.tar.gz: 60bfed82e8fd6a6c852e04afa5c0682c0bb2a4a7fd5e790a1d5e51bb204f6f9343e2d9f9de47f6717e4ede694e6410b559c1ebc0e640e9238393aecd3c33aa7a

data/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to ask-session-protocol are documented here, following
+the keep-a-changelog format.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-12
+
+### Added
+
+- **`Client`** — NDJSON protocol client over the host's stdio or a unix
+  socket: request/response correlation by id, notification queue, error
+  handling, and connection-close semantics.
+- **`Host`** — spawns `ask-app-server` as a subprocess (with a unique
+  per-spawn socket by default) or attaches to a running host over its
+  socket.
+
+### Changed
+
+- The client and host moved into this gem from the retired
+  ask-session-client (never published): one place for the session
+  protocol, matching the ask-acp/ask-mcp pattern of protocol gems
+  carrying their implementations. The JSON Schema artifact remains the
+  cross-language contract.
+
+## [0.1.0] - 2026-08-11
+
+### Added
+
+- **Canonical event vocabulary (19 types)** — `session.created/ended`,
+  `turn.started/completed/failed/aborted`, `model.streaming/thinking`,
+  `tool.use/delta/result`, `approval.required/updated`,
+  `plan.proposed/approved/rejected`, `todos.updated`, `file.changed`,
+  `error`. Every event validates its envelope (`type`/`seq`/`payload`)
+  and payload against the registry; unknown payload fields are allowed for
+  forward compatibility.
+- **Resolvable interactions** — `approval`, `plan`, and `user_input`
+  kinds with `pending/approved/rejected/responded/expired` statuses,
+  resolvable by id from any client (terminal, web console, bot).
+- **Method surface (21 methods)** — handshake (`ping`, `initialize`),
+  session lifecycle (`session/create|list|resume|subscribe|events|send|
+  abort|close`), artifacts, interactions (`interaction/list|approve|reject|
+  approve-all|reject-all|respond`), plan mode (`plan/approve|reject`), and
+  `workspace/readState`; params and results validated against the registry.
+- **Interop surface** — `interaction/requestPermission` and
+  `interaction/requestUserInput` reverse requests, matching the external
+  app-server protocol standard.
+- **Versioning** — `PROTOCOL_VERSION` (`1.0`, semver semantics: additive
+  changes bump minor, breaking changes bump major) negotiated in
+  `initialize`; `DELIVERY_KINDS` (`live`, `replay`,
+  `web-remote-replayable`).
+- **JSON Schema artifact** — `docs/ask-session-protocol.schema.json`
+  (draft 2020-12) generated from the registries via `rake schema`, so
+  non-Ruby clients can validate the contract without loading the gem.
+- **Test suite** — 64 minitest tests covering event/interaction/method
+  validation, round-trips, registry integrity, schema generation, and
+  gemspec metadata.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+# ask-session-protocol
+
+**The canonical wire protocol for ask agent sessions.**
+
+The contract between the ask session host (ask-app-server) and every client:
+terminal TUI, web console, bots, IDE integrations, CI scripts. One runtime,
+many thin clients — all speaking the same versioned vocabulary.
+
+This gem is a **definition, not an implementation**. It contains no runtime,
+no transports, and no session logic. It is the single authoritative,
+versioned artifact for what a session event looks like on the wire and which
+methods a host exposes — so the host and every client evolve independently
+against the same contract.
+
+## Why this exists
+
+The ask ecosystem previously translated `Ask::Agent` runtime events into
+three incompatible wire shapes (app-server events, harness SSE events,
+adapter events). ask-session-protocol replaces that drift with one canonical,
+versioned vocabulary, generated JSON Schema artifacts, and strict validation
+at the boundaries.
+
+```
+                    ┌───────────────────────────────────────────┐
+                    │  ask-agent (session runtime)              │
+                    └──────────────┬────────────────────────────┘
+                                   │
+              ┌────────────────────▼────────────────────┐
+              │  ask-session-protocol  ← this gem       │
+              │  events · interactions · methods        │
+              │  versions · JSON Schema                 │
+              └────────────────────┬────────────────────┘
+                                   │  the only crossing artifact
+              ┌────────────────────▼────────────────────┐
+              │  ask-app-server (THE HOST)              │
+              │  transports: in-process | stdio |       │
+              │  unix socket | SSE                      │
+              └───┬───────────┬───────────┬─────────────┘
+            terminal TUI  web console   bots/IDE
+```
+
+## The event envelope
+
+Every event on the wire has the same shape:
+
+```json
+{ "type": "model.streaming", "seq": 12, "payload": { "delta": "Hello" } }
+```
+
+* **type** — one of the canonical dot-names below (additive growth only;
+  clients must tolerate unknown types within a major protocol version)
+* **seq** — monotonically increasing per session; clients use it for
+  ordering, dedup, and replay
+* **payload** — the event body, string-keyed, validated against the registry
+
+## Event vocabulary (19 types)
+
+| Category | Events |
+| --- | --- |
+| Session lifecycle | `session.created`, `session.ended` |
+| Turn lifecycle | `turn.started`, `turn.completed`, `turn.failed`, `turn.aborted` |
+| Model output | `model.streaming`, `model.thinking` |
+| Tool execution | `tool.use`, `tool.delta`, `tool.result` |
+| Interactions | `approval.required` ✱, `approval.updated`, `plan.proposed` ✱, `plan.approved`, `plan.rejected` |
+| Session state | `todos.updated`, `file.changed` |
+| Errors | `error` |
+
+✱ — interaction events are **resolvable by id from any client** through the
+`interaction/*` and `plan/*` methods. A terminal, web console, or bot
+resolves the same pending interaction; the host tombstones delivery so each
+subscriber sees it exactly once.
+
+## Method surface (21 methods)
+
+| Group | Methods |
+| --- | --- |
+| Handshake | `ping`, `initialize` |
+| Session lifecycle | `session/create`, `session/list`, `session/resume`, `session/subscribe`, `session/events`, `session/send`, `session/abort`, `session/close` |
+| Artifacts | `session/artifacts`, `session/artifact/get` |
+| Interactions | `interaction/list`, `interaction/approve`, `interaction/reject`, `interaction/approve-all`, `interaction/reject-all`, `interaction/respond` |
+| Plan mode | `plan/approve`, `plan/reject` |
+| Workspace | `workspace/readState` |
+
+Host → client: the `session/event` notification carries canonical event
+envelopes. Reverse requests `interaction/requestPermission` and
+`interaction/requestUserInput` are defined for interop with the external
+app-server protocol standard.
+
+## Versioning
+
+* `Ask::SessionProtocol::PROTOCOL_VERSION` — the wire version, negotiated in
+  the `initialize` handshake. Bump the minor on additive changes (new
+  events, new methods); bump the major on breaking changes.
+* `Ask::SessionProtocol::VERSION` — the gem version.
+
+## Validation
+
+The registries validate everything at the boundary:
+
+```ruby
+event = Ask::SessionProtocol::Events.event(
+  type: "approval.required",
+  seq: 3,
+  payload: { "id" => "act_1", "toolName" => "bash", "args" => { "command" => "ls" } }
+)
+event.to_h # => { "type" => "approval.required", "seq" => 3, "payload" => { ... } }
+
+Ask::SessionProtocol::Methods.validate_params!("session/send", { "sessionId" => "s1", "content" => "hi" })
+# => true
+```
+
+Unknown payload fields are allowed (forward compatibility); missing required
+fields, wrong types, and out-of-enum values raise `ArgumentError`.
+
+## JSON Schema
+
+`docs/ask-session-protocol.schema.json` (draft 2020-12) is generated from the
+registries with `rake schema` and committed, so non-Ruby clients (bots, IDEs,
+) can validate against the contract without loading this gem.
+
+## Installation
+
+```ruby
+gem "ask-session-protocol"
+```
+
+## Development
+
+```
+bundle install
+rake test        # minitest suite
+rake schema      # regenerate docs/ask-session-protocol.schema.json
+```
+
+## License
+
+MIT