simple_acp 0.0.1

data/examples/03_run_management/client.rb

@@ -0,0 +1,115 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run Management Example - Client
+#
+# Demonstrates:
+# - Cancelling a running task with run_cancel
+# - Retrieving run event history with run_events
+# - Pagination of events
+#
+# First start the server: ruby examples/03_run_management/server.rb
+# Then run this client: ruby examples/03_run_management/client.rb
+
+require_relative "../../lib/simple_acp"
+
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+puts "=== Run Management Demo ==="
+puts
+
+# Verify server is running
+unless client.ping
+  puts "Server is not responding"
+  exit 1
+end
+puts "Server is healthy"
+puts
+
+# --- Demo 1: Cancelling a running task ---
+puts "--- Demo 1: Run Cancellation ---"
+puts
+
+puts "Starting a long-running cancellable task..."
+run = client.run_async(agent: "cancellable-task", input: "data processing job")
+puts "Run ID: #{run.run_id}"
+puts
+
+puts "Letting it run for 1.5 seconds..."
+sleep(1.5)
+
+status = client.run_status(run.run_id)
+puts "Current status: #{status.status}"
+puts
+
+puts "Cancelling the run..."
+cancelled_run = client.run_cancel(run.run_id)
+puts "Cancel requested. Status: #{cancelled_run.status}"
+puts
+
+# Wait a moment for cancellation to complete
+sleep(0.5)
+
+final_status = client.run_status(run.run_id)
+puts "Final status: #{final_status.status}"
+puts "Output messages:"
+final_status.output.each do |message|
+  puts "  #{message.text_content}"
+end
+puts
+
+# --- Demo 2: Let a task complete normally for comparison ---
+puts "--- Demo 2: Normal Completion (for comparison) ---"
+puts
+
+puts "Starting a shorter task (will complete normally)..."
+run = client.run_sync(agent: "cancellable-task", input: "quick task")
+puts "Status: #{run.status}"
+puts "Final message: #{run.output.last&.text_content}"
+puts
+
+# --- Demo 3: Event History ---
+puts "--- Demo 3: Event History with run_events ---"
+puts
+
+puts "Generating events..."
+run = client.run_sync(agent: "event-generator", input: "8")
+puts "Run completed with #{run.output.length} output messages"
+puts
+
+puts "Retrieving all events for this run..."
+events = client.run_events(run.run_id)
+puts "Total events retrieved: #{events.length}"
+puts
+puts "Event types:"
+event_counts = events.group_by { |e| e.class.name.split("::").last }
+event_counts.each do |type, evts|
+  puts "  #{type}: #{evts.length}"
+end
+puts
+
+puts "First 5 events:"
+events.first(5).each_with_index do |event, i|
+  event_type = event.class.name.split("::").last
+  puts "  #{i + 1}. #{event_type}"
+end
+puts
+
+# --- Demo 4: Event Pagination ---
+puts "--- Demo 4: Event Pagination ---"
+puts
+
+puts "Retrieving events with pagination (limit: 5, offset: 0)..."
+page1 = client.run_events(run.run_id, limit: 5, offset: 0)
+puts "Page 1: #{page1.length} events"
+
+puts "Retrieving events with pagination (limit: 5, offset: 5)..."
+page2 = client.run_events(run.run_id, limit: 5, offset: 5)
+puts "Page 2: #{page2.length} events"
+
+puts "Retrieving events with pagination (limit: 5, offset: 10)..."
+page3 = client.run_events(run.run_id, limit: 5, offset: 10)
+puts "Page 3: #{page3.length} events"
+puts
+
+puts "=== Run Management Demo Complete ==="

data/examples/03_run_management/server.rb

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run Management Example - Server
+#
+# Demonstrates run cancellation and event tracking.
+#
+# Run with: ruby examples/03_run_management/server.rb
+# Then connect with: ruby examples/03_run_management/client.rb
+
+require_relative "../../lib/simple_acp"
+
+server = SimpleAcp::Server::Base.new
+
+# Long-running cancellable agent
+server.agent("cancellable-task",
+  description: "A long task that can be cancelled (10 iterations)"
+) do |context|
+  task_name = context.input.first&.text_content || "unnamed task"
+
+  Enumerator.new do |yielder|
+    yielder << SimpleAcp::Server::RunYield.new(
+      SimpleAcp::Models::Message.agent("Starting: #{task_name}")
+    )
+
+    10.times do |i|
+      # Check for cancellation before each iteration
+      if context.cancelled?
+        yielder << SimpleAcp::Server::RunYield.new(
+          SimpleAcp::Models::Message.agent("Task cancelled at iteration #{i + 1}")
+        )
+        break
+      end
+
+      # Simulate work
+      if defined?(Async::Task) && Async::Task.current?
+        Async::Task.current.sleep(0.5)
+      else
+        sleep(0.5)
+      end
+
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent("Iteration #{i + 1}/10 complete")
+      )
+    end
+
+    unless context.cancelled?
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent("Task '#{task_name}' finished successfully!")
+      )
+    end
+  end
+end
+
+# Agent that generates many events for event history demo
+server.agent("event-generator",
+  description: "Generates multiple events for history tracking"
+) do |context|
+  count = context.input.first&.text_content&.to_i || 5
+  count = [count, 20].min  # Cap at 20
+
+  Enumerator.new do |yielder|
+    count.times do |i|
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent("Event #{i + 1}: Generated at #{Time.now.strftime('%H:%M:%S.%L')}")
+      )
+
+      if defined?(Async::Task) && Async::Task.current?
+        Async::Task.current.sleep(0.1)
+      else
+        sleep(0.1)
+      end
+    end
+  end
+end
+
+puts "Starting Run Management Demo Server..."
+puts "Available agents:"
+server.agents.each do |name, agent|
+  puts "  - #{name}: #{agent.description}"
+end
+puts
+
+server.run(port: 8000)

data/examples/04_rich_messages/client.rb

@@ -0,0 +1,160 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Rich Messages Example - Client
+#
+# Demonstrates:
+# - Receiving JSON content in message parts
+# - Receiving base64 encoded data (images)
+# - Receiving URL references
+# - Multi-part messages with different content types
+#
+# First start the server: ruby examples/04_rich_messages/server.rb
+# Then run this client: ruby examples/04_rich_messages/client.rb
+
+require_relative "../../lib/simple_acp"
+require "json"
+require "base64"
+
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+puts "=== Rich Messages Demo ==="
+puts
+
+# Verify server is running
+unless client.ping
+  puts "Server is not responding"
+  exit 1
+end
+puts "Server is healthy"
+puts
+
+# --- Demo 1: JSON Data ---
+puts "--- Demo 1: JSON Content ---"
+puts
+
+puts "Querying for 'users' data..."
+run = client.run_sync(agent: "json-data", input: "users")
+
+run.output.each do |message|
+  message.parts.each do |part|
+    case part.content_type
+    when "application/json"
+      puts "JSON Part:"
+      data = JSON.parse(part.content)
+      puts "  Query: #{data['query']}"
+      puts "  Count: #{data['count']}"
+      puts "  Results:"
+      data["results"]&.each do |user|
+        puts "    - #{user['name']} (#{user['role']})"
+      end
+    when "text/plain"
+      puts "Text Part: #{part.content}"
+    end
+  end
+end
+puts
+
+puts "Querying for 'stats' data..."
+run = client.run_sync(agent: "json-data", input: "stats")
+
+run.output.each do |message|
+  message.parts.each do |part|
+    if part.content_type == "application/json"
+      data = JSON.parse(part.content)
+      puts "Stats (#{data['timestamp']}):"
+      data["metrics"]&.each do |key, value|
+        puts "  #{key}: #{value}"
+      end
+    end
+  end
+end
+puts
+
+# --- Demo 2: Image/Binary Data ---
+puts "--- Demo 2: Base64 Encoded Image ---"
+puts
+
+%w[red green blue].each do |color|
+  puts "Generating #{color} circle..."
+  run = client.run_sync(agent: "image-generator", input: color)
+
+  run.output.each do |message|
+    message.parts.each do |part|
+      case part.content_type
+      when "image/svg+xml"
+        # Decode and show first line of SVG
+        svg = Base64.decode64(part.content)
+        puts "  SVG data received (#{part.content.length} bytes base64)"
+        puts "  First line: #{svg.lines.first.strip}"
+      when "text/plain"
+        puts "  #{part.content}"
+      end
+    end
+  end
+end
+puts
+
+# --- Demo 3: URL References ---
+puts "--- Demo 3: URL References ---"
+puts
+
+%w[ruby python javascript].each do |topic|
+  puts "Getting links for '#{topic}'..."
+  run = client.run_sync(agent: "link-provider", input: topic)
+
+  run.output.each do |message|
+    message.parts.each do |part|
+      if part.metadata && part.metadata["url"]
+        puts "  #{part.metadata['title']}"
+        puts "    URL: #{part.metadata['url']}"
+      elsif part.content&.include?("Found")
+        puts "  #{part.content}"
+      end
+    end
+  end
+  puts
+end
+
+# --- Demo 4: Multi-Format Response ---
+puts "--- Demo 4: Multi-Format Response ---"
+puts
+
+puts "Requesting greeting in multiple formats..."
+run = client.run_sync(agent: "multi-format", input: "Developer")
+
+run.output.each do |message|
+  puts "Message has #{message.parts.length} parts:"
+  message.parts.each_with_index do |part, i|
+    puts
+    puts "  Part #{i + 1} (#{part.content_type}):"
+    case part.content_type
+    when "application/json"
+      data = JSON.parse(part.content)
+      puts "    #{data.inspect}"
+    when "text/html"
+      # Show HTML without rendering
+      puts "    #{part.content.gsub("\n", " ").strip}"
+    else
+      puts "    #{part.content}"
+    end
+  end
+end
+puts
+
+# --- Demo 5: Content Type Inspection ---
+puts "--- Demo 5: Agent Content Type Capabilities ---"
+puts
+
+puts "Listing agents and their content types:"
+agents_response = client.agents
+agents_response.agents.each do |agent|
+  puts
+  puts "#{agent.name}:"
+  puts "  Description: #{agent.description}"
+  puts "  Input types: #{agent.input_content_types&.join(', ') || 'any'}"
+  puts "  Output types: #{agent.output_content_types&.join(', ') || 'any'}"
+end
+puts
+
+puts "=== Rich Messages Demo Complete ==="

data/examples/04_rich_messages/server.rb

@@ -0,0 +1,180 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Rich Messages Example - Server
+#
+# Demonstrates different message part types:
+# - Text content
+# - JSON content
+# - Base64 encoded data
+# - URL references
+#
+# Run with: ruby examples/04_rich_messages/server.rb
+# Then connect with: ruby examples/04_rich_messages/client.rb
+
+require_relative "../../lib/simple_acp"
+require "json"
+require "base64"
+
+server = SimpleAcp::Server::Base.new
+
+# Agent that returns JSON data
+server.agent("json-data",
+  description: "Returns structured JSON data",
+  output_content_types: ["application/json", "text/plain"]
+) do |context|
+  query = context.input.first&.text_content || "users"
+
+  # Simulate different data queries
+  data = case query.downcase
+  when "users"
+    {
+      query: "users",
+      count: 3,
+      results: [
+        { id: 1, name: "Alice", role: "admin" },
+        { id: 2, name: "Bob", role: "user" },
+        { id: 3, name: "Charlie", role: "user" }
+      ]
+    }
+  when "stats"
+    {
+      query: "stats",
+      timestamp: Time.now.iso8601,
+      metrics: {
+        requests_today: 1234,
+        active_users: 42,
+        uptime_percent: 99.9
+      }
+    }
+  else
+    {
+      query: query,
+      error: "Unknown query type",
+      available: %w[users stats]
+    }
+  end
+
+  # Return message with both JSON and text parts
+  message = SimpleAcp::Models::Message.new(
+    role: "agent",
+    parts: [
+      SimpleAcp::Models::MessagePart.json(data),
+      SimpleAcp::Models::MessagePart.text("Query '#{query}' returned #{data[:results]&.length || 0} results")
+    ]
+  )
+
+  message
+end
+
+# Agent that returns a simple image (small SVG as base64)
+server.agent("image-generator",
+  description: "Generates a simple SVG image",
+  output_content_types: ["image/svg+xml", "text/plain"]
+) do |context|
+  color = context.input.first&.text_content || "blue"
+
+  # Create a simple SVG
+  svg = <<~SVG
+    <svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+      <rect width="100" height="100" fill="transparent"/>
+      <circle cx="50" cy="50" r="40" fill="#{color}" opacity="0.8"/>
+      <text x="50" y="55" text-anchor="middle" fill="white" font-size="12">#{color}</text>
+    </svg>
+  SVG
+
+  encoded = Base64.strict_encode64(svg)
+
+  message = SimpleAcp::Models::Message.new(
+    role: "agent",
+    parts: [
+      SimpleAcp::Models::MessagePart.new(
+        kind: "data",
+        content: encoded,
+        content_type: "image/svg+xml"
+      ),
+      SimpleAcp::Models::MessagePart.text("Generated #{color} circle SVG (#{encoded.length} bytes base64)")
+    ]
+  )
+
+  message
+end
+
+# Agent that returns URL references
+server.agent("link-provider",
+  description: "Provides relevant URLs and references",
+  output_content_types: ["text/uri-list", "text/plain"]
+) do |context|
+  topic = context.input.first&.text_content || "ruby"
+
+  links = case topic.downcase
+  when "ruby"
+    [
+      { url: "https://www.ruby-lang.org/", title: "Ruby Official Site" },
+      { url: "https://rubygems.org/", title: "RubyGems" },
+      { url: "https://guides.rubyonrails.org/", title: "Rails Guides" }
+    ]
+  when "python"
+    [
+      { url: "https://www.python.org/", title: "Python Official Site" },
+      { url: "https://pypi.org/", title: "PyPI" },
+      { url: "https://docs.python.org/", title: "Python Docs" }
+    ]
+  else
+    [
+      { url: "https://www.google.com/search?q=#{topic}", title: "Search for #{topic}" }
+    ]
+  end
+
+  # Create message with URL parts
+  parts = links.map do |link|
+    SimpleAcp::Models::MessagePart.new(
+      kind: "text",
+      content: "#{link[:title]}: #{link[:url]}",
+      content_type: "text/plain",
+      metadata: { url: link[:url], title: link[:title] }
+    )
+  end
+
+  parts << SimpleAcp::Models::MessagePart.text("Found #{links.length} links for '#{topic}'")
+
+  SimpleAcp::Models::Message.new(role: "agent", parts: parts)
+end
+
+# Agent demonstrating multi-part responses
+server.agent("multi-format",
+  description: "Returns data in multiple formats",
+  output_content_types: ["application/json", "text/plain", "text/html"]
+) do |context|
+  name = context.input.first&.text_content || "World"
+
+  # Return same greeting in multiple formats
+  message = SimpleAcp::Models::Message.new(
+    role: "agent",
+    parts: [
+      SimpleAcp::Models::MessagePart.text("Hello, #{name}!"),
+      SimpleAcp::Models::MessagePart.json({ greeting: "Hello", recipient: name, timestamp: Time.now.iso8601 }),
+      SimpleAcp::Models::MessagePart.new(
+        kind: "text",
+        content: "<h1>Hello, #{name}!</h1><p>Welcome to the multi-format demo.</p>",
+        content_type: "text/html"
+      )
+    ]
+  )
+
+  message
+end
+
+puts "Starting Rich Messages Demo Server..."
+puts "Available agents:"
+server.agents.each do |name, agent|
+  puts "  - #{name}: #{agent.description}"
+  puts "    Input types: #{agent.manifest.input_content_types.join(', ')}"
+  puts "    Output types: #{agent.manifest.output_content_types.join(', ')}"
+  if agent.manifest.metadata
+    puts "    Has metadata: yes"
+  end
+end
+puts
+
+server.run(port: 8000)

data/examples/05_await_resume/client.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Await/Resume Example - Client
+#
+# Demonstrates:
+# - Detecting when a run is awaiting input
+# - Resuming a run with run_resume_sync
+# - Multi-step interactive flows
+# - Streaming resume with run_resume_stream
+#
+# First start the server: ruby examples/05_await_resume/server.rb
+# Then run this client: ruby examples/05_await_resume/client.rb
+
+require_relative "../../lib/simple_acp"
+
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+puts "=== Await/Resume Demo ==="
+puts
+
+# Verify server is running
+unless client.ping
+  puts "Server is not responding"
+  exit 1
+end
+puts "Server is healthy"
+puts
+
+# --- Demo 1: Simple greeter with await/resume ---
+puts "--- Demo 1: Simple Greeter (Single Await) ---"
+puts
+
+puts "Starting greeter agent..."
+run = client.run_sync(agent: "greeter", input: "start")
+
+if run.status == "awaiting"
+  puts "Status: #{run.status}"
+  puts "Agent asks: #{run.await_request&.message&.text_content}"
+  puts
+
+  # Resume with our response
+  puts "Responding with: 'Alice'"
+  resume = SimpleAcp::Models::MessageAwaitResume.new(
+    message: SimpleAcp::Models::Message.user("Alice")
+  )
+
+  completed_run = client.run_resume_sync(run_id: run.run_id, await_resume: resume)
+  puts "Status: #{completed_run.status}"
+  puts "Agent says: #{completed_run.output.last&.text_content}"
+else
+  puts "Unexpected status: #{run.status}"
+end
+puts
+
+# --- Demo 2: Multi-step survey ---
+puts "--- Demo 2: Multi-Step Survey (Multiple Awaits) ---"
+puts
+
+puts "Starting survey..."
+run = client.run_sync(agent: "survey", input: "begin")
+
+responses = ["Bob", "blue", "42"]
+response_index = 0
+
+while run.status == "awaiting"
+  puts "Agent asks: #{run.await_request&.message&.text_content}"
+
+  if response_index < responses.length
+    response = responses[response_index]
+    puts "Responding with: '#{response}'"
+    puts
+
+    resume = SimpleAcp::Models::MessageAwaitResume.new(
+      message: SimpleAcp::Models::Message.user(response)
+    )
+
+    run = client.run_resume_sync(run_id: run.run_id, await_resume: resume)
+    response_index += 1
+  else
+    puts "ERROR: Ran out of responses!"
+    break
+  end
+end
+
+if run.status == "completed"
+  puts "Survey completed!"
+  puts run.output.last&.text_content
+else
+  puts "Unexpected final status: #{run.status}"
+end
+puts
+
+# --- Demo 3: Confirmation agent - Yes case ---
+puts "--- Demo 3: Confirmation (Yes) ---"
+puts
+
+puts "Requesting action: 'delete all files'"
+run = client.run_sync(agent: "confirmer", input: "delete all files")
+
+if run.status == "awaiting"
+  puts "Agent asks: #{run.await_request&.message&.text_content}"
+  puts "Responding with: 'yes'"
+
+  resume = SimpleAcp::Models::MessageAwaitResume.new(
+    message: SimpleAcp::Models::Message.user("yes")
+  )
+
+  completed_run = client.run_resume_sync(run_id: run.run_id, await_resume: resume)
+  puts "Result: #{completed_run.output.last&.text_content}"
+end
+puts
+
+# --- Demo 4: Confirmation agent - No case ---
+puts "--- Demo 4: Confirmation (No) ---"
+puts
+
+puts "Requesting action: 'format hard drive'"
+run = client.run_sync(agent: "confirmer", input: "format hard drive")
+
+if run.status == "awaiting"
+  puts "Agent asks: #{run.await_request&.message&.text_content}"
+  puts "Responding with: 'no'"
+
+  resume = SimpleAcp::Models::MessageAwaitResume.new(
+    message: SimpleAcp::Models::Message.user("no")
+  )
+
+  completed_run = client.run_resume_sync(run_id: run.run_id, await_resume: resume)
+  puts "Result: #{completed_run.output.last&.text_content}"
+end
+puts
+
+# --- Demo 5: Streaming resume ---
+puts "--- Demo 5: Streaming Resume ---"
+puts
+
+puts "Starting greeter with streaming resume..."
+run = client.run_sync(agent: "greeter", input: "start")
+
+if run.status == "awaiting"
+  puts "Agent asks: #{run.await_request&.message&.text_content}"
+  puts "Resuming with streaming..."
+
+  resume = SimpleAcp::Models::MessageAwaitResume.new(
+    message: SimpleAcp::Models::Message.user("Charlie")
+  )
+
+  print "Events: "
+  client.run_resume_stream(run_id: run.run_id, await_resume: resume) do |event|
+    case event
+    when SimpleAcp::Models::RunInProgressEvent
+      print "[in_progress] "
+    when SimpleAcp::Models::MessageCreatedEvent
+      print "[message] "
+    when SimpleAcp::Models::RunCompletedEvent
+      puts "[completed]"
+      puts "Final output: #{event.run.output.last&.text_content}"
+    end
+  end
+end
+puts
+
+puts "=== Await/Resume Demo Complete ==="