acp_sdk_async 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 311898f67ba8c2701c3edcebe315120d09f5b445d5bc32b7c31719d4973f9b7c
-  data.tar.gz: d94e9ce7d8da1bb16017c77ee562b87fe8492f5ea60467042a97aa20f4c33493
+  metadata.gz: 71071f49bdb82be3e735ea3d15e8cd3b7969ef24308f576a1b48c88064793e15
+  data.tar.gz: 647de2c4fabcbac7d7f19c4f7d078559f377d26ba29455c6559933be6c72089f
 SHA512:
-  metadata.gz: 0c65a6d278fd08ce6e9fb08cbda659c1eb3fd5805a43f345514ef6cb516534a76c89acb1aa8fc1d99d2fcde0ee92453db1268144884dd87097ba7b1892857f3a
-  data.tar.gz: 014db843ff5839284074e89f56acdb18eacdc8de8387d678892b345b56bd1392fe4232637fb4506623d0c8b2f02e37347114859de8ea44db7381345e3a30ed8a
+  metadata.gz: b2aedef677d4253e0ee4586bc993ab3b75392b60e985a2d9ac2c25158969fa24b6bfd40fd6f845afb2bba02a1735726fc0f42efcbf4da5360cf821515c70be2a
+  data.tar.gz: 8555c782250e074c7c300771f718da95c5cae4492f3a16ff4ed437ea30e80d2a05274216c5c2b73e63fdf4c2647ddb65b81ad0f411aa7b58ba17f2b75c27083e

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.2]
+
+### Added
+
+- `examples/duet.rb`: runnable in-process agent↔client demo over
+  in-memory transports (covered by `test/examples_test.rb`).
+- Windows inherited-env allowlist for spawned agents
+  (`APPDATA`, `PATHEXT`, …); process management itself stays POSIX-only.
+  Untested: there is no Windows CI yet.
+
+### Fixed
+
+- `NdjsonTransport` caps inbound lines at 50MB by default
+  (`max_line_bytes:`): over-long lines are skipped instead of
+  ballooning memory. Lines are reassembled in 64KB chunks.
+
 ## [0.3.1]
 
 ### Fixed

data/README.md

@@ -122,7 +122,11 @@ block.to_h         # => { "type" => "text", "text" => "hi" }
 
 ## Lower level
 
-`ACP::Connection` is the transport-agnostic JSON-RPC layer (requests with optional timeouts, ordered notification delivery, observers for tracing traffic). `ACP::NdjsonTransport` wraps a pair of IO objects; `ACP::MemoryTransport.pair` gives two in-memory ends for tests.
+`ACP::Connection` is the transport-agnostic JSON-RPC layer (requests with optional timeouts, ordered notification delivery, observers for tracing traffic). `ACP::NdjsonTransport` wraps a pair of IO objects; `ACP::MemoryTransport.pair` gives two in-memory ends for tests. Inbound lines are capped at 50MB by default (`max_line_bytes:`) so a rogue peer cannot exhaust memory.
+
+Spawning and signal handling (`ACP::Stdio.spawn_agent`, `AgentProcess#kill`) target POSIX platforms. The Windows inherited-environment allowlist ships untested — there is no Windows CI yet.
+
+See `examples/duet.rb` for a runnable in-process agent↔client demo (`ruby -Ilib examples/duet.rb "hello"`).
 
 Logging goes through `ACP.logger` (a `Logger`, `WARN` level by default); assign your own to integrate with the host application.
 

data/examples/duet.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# In-process agent<->client demo over in-memory transports (no subprocess).
+#
+# Run with:
+#   ruby -Ilib examples/duet.rb ["message 1" "message 2" ...]
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "acp_sdk_async"
+
+S = ACP::Schema
+
+# Minimal agent: echoes prompts back with a "Client sent:" preamble.
+class DuetAgent
+  def on_connect(connection)
+    @connection = connection
+  end
+
+  def initialize_acp(request)
+    S::InitializeResponse.new(
+      protocol_version: request.protocol_version,
+      agent_info: S::Implementation.new(name: "duet-agent", version: "0.1.0")
+    )
+  end
+
+  def new_session(_request)
+    S::NewSessionResponse.new(session_id: "duet-1")
+  end
+
+  def prompt(request)
+    text = request.prompt.map { |block| block.respond_to?(:text) ? block.text : "" }.join
+    @connection.session_update(
+      session_id: request.session_id,
+      update: S::AgentMessageChunk.new(content: S::TextContentBlock.new(text: "Client sent:"))
+    )
+    @connection.session_update(
+      session_id: request.session_id,
+      update: S::AgentMessageChunk.new(content: S::TextContentBlock.new(text: text))
+    )
+    S::PromptResponse.new(stop_reason: "end_turn")
+  end
+
+  def cancel(_notification); end
+end
+
+# Minimal client: prints agent message chunks.
+class DuetClient
+  def session_update(notification)
+    update = notification.update
+    return unless update.is_a?(S::AgentMessageChunk) && update.content.is_a?(S::TextContentBlock)
+
+    puts "| Agent: #{update.content.text}"
+  end
+end
+
+Sync do
+  client_transport, agent_transport = ACP.memory_transport_pair
+  agent_conn = ACP::Agent::Connection.new(DuetAgent.new, agent_transport)
+  client_conn = ACP::Client::Connection.new(DuetClient.new, client_transport)
+  agent_conn.start
+  client_conn.start
+
+  begin
+    client_conn.initialize_agent(
+      client_info: S::Implementation.new(name: "duet-client", version: "0.1.0")
+    )
+    session = client_conn.new_session(cwd: Dir.pwd)
+
+    messages = ARGV.empty? ? ["Hello, agent!"] : ARGV
+    messages.each do |text|
+      puts "> #{text}"
+      client_conn.prompt(
+        session_id: session.session_id,
+        prompt: [S::TextContentBlock.new(text: text)]
+      )
+    end
+  ensure
+    client_conn.close
+    agent_conn.close
+  end
+end

data/lib/acp/exceptions.rb

@@ -29,4 +29,8 @@ module ACP
   class ConnectionError < Error; end
 
   class TimeoutError < Error; end
+
+  # Raised when a single NDJSON line exceeds the transport's cap.
+  # Never escapes NdjsonTransport: receive_message skips the line.
+  class LineTooLongError < Error; end
 end

data/lib/acp/stdio.rb

@@ -7,10 +7,15 @@ require_relative "wait"
 module ACP
   module Stdio
     DEFAULT_INHERITED_ENV = %w[HOME LOGNAME PATH SHELL TERM USER].freeze
+    WINDOWS_INHERITED_ENV = %w[
+      APPDATA HOMEDRIVE HOMEPATH LOCALAPPDATA PATH PATHEXT
+      PROCESSOR_ARCHITECTURE SYSTEMDRIVE SYSTEMROOT TEMP USERNAME USERPROFILE
+    ].freeze
 
     def self.default_environment
+      keys = Gem.win_platform? ? WINDOWS_INHERITED_ENV : DEFAULT_INHERITED_ENV
       env = {}
-      DEFAULT_INHERITED_ENV.each do |key|
+      keys.each do |key|
         value = ENV.fetch(key, nil)
         next if value.nil? || value.start_with?("()")
 

data/lib/acp/transport.rb

@@ -26,12 +26,20 @@ module ACP
   class NdjsonTransport
     include Transport
 
+    # Parity with the reference 50MB stdio buffer: inbound lines are
+    # reassembled in bounded chunks and a line beyond the cap is skipped,
+    # so a rogue peer cannot exhaust memory via stdout. (The reference
+    # accepts such lines; we deliberately reject them instead.)
+    DEFAULT_MAX_LINE_BYTES = 50 * 1024 * 1024
+    READ_CHUNK_BYTES = 64 * 1024
+
     attr_reader :input, :output
 
-    def initialize(input, output, receive_timeout: nil)
+    def initialize(input, output, receive_timeout: nil, max_line_bytes: DEFAULT_MAX_LINE_BYTES)
       @input = input
       @output = output
       @receive_timeout = receive_timeout
+      @max_line_bytes = max_line_bytes
       @write_mutex = Mutex.new
       @closed = false
       @output.sync = true if @output.respond_to?(:sync=)
@@ -55,7 +63,12 @@ module ACP
 
     def receive_message
       loop do
-        line = read_line
+        begin
+          line = read_line
+        rescue LineTooLongError => e
+          ACP.logger.warn("acp: skipping over-long line: #{e.message}")
+          next
+        end
         return nil if line.nil?
 
         line = line.scrub unless line.valid_encoding?
@@ -84,22 +97,54 @@ module ACP
     private
 
     def read_line
-      return @input.gets unless @receive_timeout
+      return read_line_chunks unless @receive_timeout
 
       if Wait.async?
         begin
-          ::Async::Task.current.with_timeout(@receive_timeout) { @input.gets }
+          ::Async::Task.current.with_timeout(@receive_timeout) { read_line_chunks }
         rescue ::Async::TimeoutError
           raise TimeoutError, "No message received within #{@receive_timeout}s"
         end
       elsif @input.respond_to?(:wait_readable)
         raise TimeoutError, "No message received within #{@receive_timeout}s" unless @input.wait_readable(@receive_timeout)
 
-        @input.gets
+        read_line_chunks
       else
         raise TimeoutError, "No message received within #{@receive_timeout}s" unless IO.select([@input], nil, nil, @receive_timeout)
 
-        @input.gets
+        read_line_chunks
+      end
+    end
+
+    # Reads one "\n"-terminated line in bounded chunks so a giant line never
+    # sits in memory twice. Returns nil on EOF (or the trailing partial line,
+    # like a short read). Raises LineTooLongError after discarding the rest
+    # of an over-long line to keep framing in sync.
+    def read_line_chunks
+      buffer = nil
+      loop do
+        chunk = @input.gets("\n", READ_CHUNK_BYTES)
+        if chunk.nil?
+          return nil if buffer.nil? || buffer.empty?
+
+          return buffer
+        end
+        buffer = chunk.dup.clear if buffer.nil?
+        buffer << chunk
+        if buffer.bytesize > @max_line_bytes
+          discard_line_rest(chunk)
+          raise LineTooLongError, "line exceeds #{@max_line_bytes} bytes"
+        end
+        return buffer if chunk.end_with?("\n")
+      end
+    end
+
+    def discard_line_rest(last_chunk)
+      return if last_chunk.end_with?("\n")
+
+      loop do
+        chunk = @input.gets("\n", READ_CHUNK_BYTES)
+        return if chunk.nil? || chunk.end_with?("\n")
       end
     end
   end

data/lib/acp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ACP
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acp_sdk_async
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - nutsoriginal
@@ -46,6 +46,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- examples/duet.rb
 - lib/acp/agent.rb
 - lib/acp/client.rb
 - lib/acp/connection.rb