ask-acp 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9d8c5d492781299113b2b1f4e8f3c0c0043ffaad0304c6979505c09aa3ce536
-  data.tar.gz: c9b1162bb257e63a11be000ddf22f88a4efeb3e0832d51aeeca77c71690c06e8
+  metadata.gz: dd22248dd65fb612b9ff352e2278bc7ed8d0e2c8b86bd6e31f89752cf7b094cb
+  data.tar.gz: d9d788c986270c49e7469a877215c07f12f43e2911099b1ae06211894d400b5b
 SHA512:
-  metadata.gz: df1234934109a935b005fd481c5694f390e9e291f24e88c81dfc7bc3542bd0c9a1e3bf5149950f1d4827b97f78a7631012023608350ade6bbe190af8362b2d2e
-  data.tar.gz: 844ab3a94efae5534d5f720e60f93428411cc0a3b28bcebccfd7c5606ee5b05d18127243d543186d3dd0d763cc298fb8ca9d85de09b81a8c1378f4b4f14fa198
+  metadata.gz: 33bcddcd90137d5ae67e565030a6051ef1a910d1bc102096a03e2cf2d30316c3d7e9fa89d1bf35fda9bb8f4eac06c3a94b7d0602fc12fb5eb876bfa872c0963d
+  data.tar.gz: 5ed550a8037651b58e72037d728b592a44ac116e4b29dfceac2134a24c1f308b8a04ae171693ef61e6730a626f43c78d8e75871750892ed7460b6bef6f68783a

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,100 @@
+# ask-acp
+
+[![Gem Version](https://badge.fury.io/rb/ask-acp.svg)](https://badge.fury.io/rb/ask-acp)
+
+A Ruby implementation of the Agent Client Protocol (ACP): JSON-RPC 2.0 over
+stdio, following the v0.11.3 protocol schema. It provides a client that drives
+an ACP-compliant coding agent as a subprocess, a server base class for making
+a Ruby agent speak ACP, and a replay client for deterministic testing.
+
+## Installation
+
+```ruby
+gem "ask-acp"
+```
+
+## Quick Start
+
+### Client: drive an ACP agent subprocess
+
+```ruby
+require "ask-acp"
+
+client = Ask::ACP::Client.new(command: ["codex", "acp"])
+client.start
+client.initialize!(client_name: "my-app", client_version: "0.1.0")
+
+session = client.session_new(cwd: "/tmp")
+
+# Stream prompt events as they arrive
+client.session_prompt(session[:id], "Hello!") do |event|
+  puts "#{event[:method]}: #{event[:params]}"
+end
+
+client.stop
+```
+
+### Server: speak ACP as a Ruby agent
+
+```ruby
+class MyAgent < Ask::ACP::Server
+  def handle_session_new(params)
+    { session: { id: SecureRandom.uuid, status: "running" } }
+  end
+end
+
+MyAgent.new.run
+```
+
+## Key entry points
+
+- `Ask::ACP::Client` - spawns an agent CLI subprocess with Open3 and speaks
+  ACP over stdio. Methods: `initialize!`, `authenticate`, `session_new`,
+  `session_load`, `session_list`, `session_fork`, `session_resume`,
+  `session_close`, `session_prompt` (streams events via a block),
+  `session_cancel`, `session_set_config_option`, `session_set_mode`,
+  `session_set_model`, `start`, `stop`.
+- `Ask::ACP::Server` - base class to subclass; implement `handle_*` methods
+  and run with `.run`.
+- `Ask::ACP::ReplayClient` - replays pre-recorded JSONL interactions from a
+  fixture file. No subprocess; instant, deterministic responses.
+- `Ask::ACP::Protocol` - message builders and constants:
+  `AGENT_METHODS`, `CLIENT_METHODS`, `PROMPT_EVENTS`, `STATUSES`,
+  `PROTOCOL_VERSION`.
+- `Ask::ACP::Error` and `Ask::ACP::TimeoutError` - errors raised by the
+  client.
+
+## Full documentation
+
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
+The guide — [ACP Client & Server](https://ask-rb.github.io/ask-docs/core/acp) —
+is the narrative walkthrough: driving real agents, hosting your own, the
+session lifecycle, streamed events, and testing. The
+[Gem Index](https://ask-rb.github.io/ask-docs/reference/gems) covers ask-acp
+in depth.
+
+## Recording fixtures
+
+`record_acp` (installed with the gem) spawns a real agent and records a
+session flow to a JSONL fixture for later replay:
+
+```
+record_acp opencode fixtures/opencode_session.jsonl
+```
+
+```ruby
+client = Ask::ACP::ReplayClient.new(fixture_path: "fixtures/opencode_session.jsonl")
+client.start
+client.initialize!(client_name: "my-app", client_version: "0.1.0")
+```
+
+## Development
+
+```
+bundle install
+bundle exec ruby -Itest test/acp_test.rb
+```
+
+## License
+
+MIT

data/exe/record_acp

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Record ACP interactions to a fixture file for later replay.
+# Usage: OPENCODE_API_KEY=sk-... ruby bin/record_acp opencode fixtures/opencode_session.jsonl
+#
+# This spawns the agent, runs through a standard session flow,
+# and saves all JSON-RPC messages to a fixture file.
+
+require "json"
+require "open3"
+require "fileutils"
+
+agent = ARGV[0] || "opencode"
+output = ARGV[1] || "fixtures/#{agent}_session.jsonl"
+
+commands = {
+  "opencode" => ["opencode", "acp"],
+  "codex" => ["codex", "app-server", "--stdio"],
+}
+
+cmd = commands[agent] || [agent]
+puts "Recording ACP interaction with: #{cmd.join(" ")}"
+puts "Output: #{output}"
+
+FileUtils.mkdir_p(File.dirname(output))
+File.open(output, "w") do |fixture|
+  stdin, stdout, stderr, thr = Open3.popen3(*cmd)
+  
+  writer = Thread.new do
+    # Run through a standard session flow
+    requests = [
+      { method: "initialize", params: { protocolVersion: 1, clientInfo: { name: "askoda-record", version: "0.1.0" }, capabilities: {} } },
+      { method: "session/new", params: { cwd: Dir.pwd, mcpServers: [] } },
+    ]
+
+    requests.each do |req|
+      msg = { jsonrpc: "2.0", id: Time.now.to_i, method: req[:method], params: req[:params] }
+      fixture.puts(JSON.generate({ request: msg }))
+      stdin.puts(JSON.generate(msg))
+      stdin.flush
+      sleep 0.5
+    end
+  end
+
+  reader = Thread.new do
+    stdout.each_line do |line|
+      line = line.strip
+      next if line.empty?
+      begin
+        msg = JSON.parse(line)
+        if msg["id"]
+          fixture.puts(JSON.generate({ response: msg }))
+        else
+          fixture.puts(JSON.generate({ notification: msg }))
+        end
+      rescue JSON::ParserError
+        # Skip non-JSON output
+      end
+    end
+  end
+
+  writer.join
+  sleep 2
+  stdin.close rescue nil
+  thr.join(5) rescue nil
+  stdout.close rescue nil
+  stderr.close rescue nil
+end
+
+puts "Done! Recorded #{File.size(output)} bytes to #{output}"
+puts "Replay with: Ask::ACP::ReplayClient.new(fixture_path: '#{output}')"

data/lib/ask/acp/replay_client.rb

@@ -95,26 +95,38 @@ module Ask
         prompt_blocks = prompt.is_a?(Array) ? prompt : [{ type: "text", text: prompt.to_s }]
         params = { sessionId: session_id, prompt: prompt_blocks }
 
-        # Dispatch any notifications before the response
-        while @index < @events.length
-          event = @events[@index]
-          break if event.key?("response")
-          if event.key?("notification")
-            dispatch_event(event["notification"])
-          end
-          @index += 1
+        # Same block form as Client: a temporary handler that streams events
+        # as { method:, params: } before the response arrives.
+        handler = nil
+        if block
+          handler = ->(msg) { block.call(method: msg["method"], params: msg["params"] || {}) if msg["method"] }
+          on_notification(&handler)
         end
 
-        # Get the response
-        event = @events[@index]
-        @index += 1
-        if event && event["response"]
-          result = event["response"]["result"]
-          error = event["response"]["error"]
-          raise Error.new("[#{error["code"]}] #{error["message"]}") if error
-          result
-        else
-          { "status" => "completed" }
+        begin
+          # Dispatch any notifications before the response
+          while @index < @events.length
+            event = @events[@index]
+            break if event.key?("response")
+            if event.key?("notification")
+              dispatch_event(event["notification"])
+            end
+            @index += 1
+          end
+
+          # Get the response
+          event = @events[@index]
+          @index += 1
+          if event && event["response"]
+            result = event["response"]["result"]
+            error = event["response"]["error"]
+            raise Error.new("[#{error["code"]}] #{error["message"]}") if error
+            result
+          else
+            { "status" => "completed" }
+          end
+        ensure
+          @mutex.synchronize { @event_handlers.delete(handler) } if handler
         end
       end
 

data/lib/ask/acp/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module ACP
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: ask-acp
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Kaka Ruto
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -84,10 +84,14 @@ description: Ruby implementation of the Agent Client Protocol (ACP) — a JSON-R
   (host Ruby agents via ACP), and transport layer.
 email:
 - kaka@myrrlabs.com
-executables: []
+executables:
+- record_acp
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
+- exe/record_acp
 - lib/ask-acp.rb
 - lib/ask/acp.rb
 - lib/ask/acp/client.rb