terret-acp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6768e0a21e9c1e042f86d7d1383dd7e0f3a8175046627b3945b4686c751e1b72
+  data.tar.gz: 0d932c2745d9433ebe4d6c1f274b6a74353368b0ea56e85de36ae66e159d08bf
+SHA512:
+  metadata.gz: 3b4622c40470085dbcef9924326d89f4914624e2107e91b4e252f57753ca50c1b72c959e67a68c503c59258541c7d72c87a9d4acd0cfbe265adaefde9a8c0f73
+  data.tar.gz: 391b0f75b3b887bdadc665c1e2c33eb7a599c96ab6b3ecedb659d805997ee0c321000e0a1b69b1d1d779777302ee9d74429fc2c409dac3b3393a048f8a1ae647

data/lib/terret/acp/bounded_queue.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "async/notification"
+
+module Terret
+  module ACP
+    # Outbound frame queue: non-blocking producer, waiting consumer — the same
+    # shape terret-ws uses (ws/bounded_queue.rb), and for the same reason. The
+    # producer is `session/event` dispatch, which `Sessions#fan_out` runs
+    # SYNCHRONOUSLY inside its drainer: if the write to a slow editor's pipe
+    # parked there, every agent's event dispatch in the whole process would
+    # stall behind it (co-mounted ws clients, the titler, the compactor) and the
+    # emit queue would grow unbounded. So `push` returns false when full instead
+    # of blocking, and a dedicated writer fiber — never the drainer — is the one
+    # that may park on the pipe.
+    #
+    # Trimmed from ws's: no `wait_push`, because ACP has no replay path that
+    # needs a blocking producer. Every ACP producer is on the dispatch side and
+    # must stay non-blocking.
+    class BoundedQueue
+      def initialize(limit)
+        @limit = limit
+        @items = []
+        @closed = false
+        @waiting = Async::Notification.new
+      end
+
+      def push(item)
+        return false if @closed || @items.size >= @limit
+
+        @items << item
+        @waiting.signal
+        true
+      end
+
+      # Blocks until an item arrives or the queue closes; nil means
+      # closed-and-drained.
+      def pop
+        loop do
+          return @items.shift unless @items.empty?
+          return nil if @closed
+
+          @waiting.wait
+        end
+      end
+
+      def closed? = @closed
+
+      def close
+        @closed = true
+        @waiting.signal
+      end
+    end
+  end
+end

data/lib/terret/acp/server.rb

@@ -0,0 +1,432 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "wire"
+require_relative "bounded_queue"
+
+module Terret
+  module ACP
+    # The ACP v1 protocol engine (docs/acp.md). It is to terret-acp what
+    # Connection is to terret-ws: transport-facing, holding no session
+    # vocabulary of its own. It consumes `session/event` and projects it to
+    # `session/update` notifications, and it drives `ctx[:loop]` — the exact
+    # two-seam shape the socket uses, with JSON-RPC over stdio as the only new
+    # thing. Nothing reaches the editor that is not in the log first.
+    #
+    # One connection, many sessions: unlike the socket's one-connection-per-
+    # agent rule, an editor calls `session/new` repeatedly over a single
+    # stdio pair, so the server routes prompts and cancels by `sessionId` and
+    # keys agents `agent-#{sid}` (spawn_agent's default, same as ws).
+    #
+    # Concurrency (plan §8): the read loop PARKS the fiber on `input.gets`, it
+    # never blocks the thread — one reactor drives every agent in the process.
+    # A turn runs in a task rooted on `runner_task` (the server task, not the
+    # read loop), so a disconnect cannot cancel a turn in flight.
+    #
+    # Outbound is DECOUPLED from the event bus, exactly as terret-ws decouples
+    # it (ws/connection.rb): `project` runs inside `Sessions#fan_out`'s
+    # synchronous drainer, so if it wrote to a slow editor's pipe directly it
+    # would park that drainer and stall every agent's event dispatch in the
+    # process. Instead every producer ENQUEUES a frame (non-blocking) onto a
+    # bounded queue, and one dedicated writer fiber is the only thing that ever
+    # parks on the pipe. That writer is also the single serialization point, so
+    # a streaming turn's notifications and a request's response never interleave
+    # without a mutex. A queue that fills means the editor stopped reading:
+    # its output is dropped rather than blocking the bus (finding: a lagging
+    # editor must never wedge other sessions).
+    class Server
+      PROTOCOL_VERSION = 1
+
+      # Bounds the outbound queue so a stalled editor cannot grow it without
+      # limit. Not config: it is a safety bound, not a knob (the acp row has no
+      # config surface). Injectable so a test can force the lag path.
+      DEFAULT_QUEUE_LIMIT = 512
+
+      # Std-roster tool -> ACP ToolKind (docs/acp.md, "Resolved in Task 7").
+      # Everything not here — Task, every mcp__<server>__<tool> whose name
+      # arrives at runtime, any third-party tool — falls to the enum's own
+      # `other`.
+      TOOL_KINDS = {
+        "Read" => "read",
+        "Glob" => "search", "Grep" => "search",
+        "Write" => "edit", "Edit" => "edit",
+        "Bash" => "execute",
+        "WebFetch" => "fetch"
+      }.freeze
+
+      def initialize(ctx:, input:, output:, runner_task: Async::Task.current,
+                     queue_limit: DEFAULT_QUEUE_LIMIT)
+        @ctx = ctx
+        @input = input
+        @output = output
+        @runner_task = runner_task
+        @queue = BoundedQueue.new(queue_limit)
+        @sessions = {}  # sessionId => Agent, this connection's sessions
+        @pending = {}   # sessionId => the request id of its pending session/prompt
+        @announced = {} # toolCallId => true, tool_calls this connection has sent
+        @tail = nil
+      end
+
+      # Serve until the input closes. One listener projects every durable append
+      # for our sessions onto the queue; a writer fiber drains the queue to the
+      # output; the read loop dispatches inbound frames. The writer is rooted on
+      # this connection's own task so it dies with the connection — unlike turn
+      # tasks, which root on runner_task and outlive it.
+      def run
+        @tail = @ctx.on("session/event") { |ev| project(ev) }
+        Sync do |task|
+          writer = task.async { drain_writes }
+          read_loop
+        ensure
+          # EOF disposes the connection, NOT the agents (docs/acp.md): they stay
+          # in the loop registry, parked per the M6 lifecycle, and re-attach
+          # through session/prompt. Closing the queue lets the writer flush what
+          # is already queued, then end.
+          @tail&.call
+          @tail = nil
+          @queue.close
+          writer&.wait
+        end
+      end
+
+      private
+
+      # -- transport -------------------------------------------------------------
+
+      def read_loop
+        while (line = @input.gets)
+          text = line.chomp
+          next if text.empty? # a blank line between frames is noise, not a parse error
+
+          dispatch(text)
+        end
+      rescue IOError, SystemCallError
+        # The input was closed under us (the editor died mid-read) rather than
+        # reaching a clean EOF; either way there is nothing more to read.
+        nil
+      end
+
+      # The only fiber that may park on the pipe. A slow editor parks it here,
+      # never the event-bus drainer.
+      def drain_writes
+        while (frame = @queue.pop)
+          @output.write("#{frame}\n")
+          @output.flush if @output.respond_to?(:flush)
+        end
+      rescue IOError, SystemCallError => e
+        # The editor is gone (a broken pipe). Stop writing and close the queue so
+        # producers lag immediately rather than filling the bound; the read loop
+        # winds down at EOF and the agents survive, their turns logged durably.
+        warn "terret-acp: writer stopped (client gone?): #{e.class}: #{e.message}"
+        @queue.close
+      end
+
+      # Non-blocking, always — this is called from the event-bus drainer, from
+      # the read loop, and from turn tasks, and none of them may block on a slow
+      # pipe. A full queue means the editor stopped reading.
+      def enqueue(frame)
+        return if @queue.push(frame)
+
+        lag!
+      end
+
+      # The editor fell too far behind. Drop its output rather than block the
+      # shared bus; the connection lingers reading until EOF, producing nothing.
+      def lag!
+        return if @queue.closed?
+
+        warn "terret-acp: client lagged; dropping output (agents survive, turns still log)"
+        @queue.close
+      end
+
+      # -- inbound ---------------------------------------------------------------
+
+      def dispatch(line)
+        msg = Wire.decode(line)
+        case msg.kind
+        when :parse_error then enqueue(Wire.error(id: nil, code: -32700, message: "parse error"))
+        when :invalid then enqueue(Wire.error(id: msg.id, code: -32600, message: "invalid request"))
+        when :notification then handle_notification(msg)
+        when :request then handle_request(msg)
+        # :response — this server sends no requests to the client, so an
+        # inbound response correlates with nothing; drop it rather than error.
+        end
+      rescue StandardError => e
+        # A bug handling one frame must never kill the read loop: an editor that
+        # sends something we mishandle gets an answer (if it was a request) and
+        # the loop reads on.
+        warn "terret-acp: dropping frame on dispatch error: #{e.class}: #{e.message}"
+        enqueue(Wire.error(id: msg&.id, code: -32603, message: "internal error")) if msg&.request?
+      end
+
+      def handle_request(msg)
+        params = msg.params.is_a?(Hash) ? msg.params : {}
+        case msg.method
+        when "initialize" then enqueue(Wire.response(id: msg.id, result: initialize_result))
+        when "session/new" then new_session(msg.id, params)
+        when "session/prompt" then prompt(msg.id, params)
+        else
+          # Every unimplemented method, including authenticate (authMethods is
+          # empty, so it is never reached) and every v2 name, answers here.
+          enqueue(Wire.error(id: msg.id, code: -32601, message: "method not found: #{msg.method}"))
+        end
+      end
+
+      def handle_notification(msg)
+        params = msg.params.is_a?(Hash) ? msg.params : {}
+        case msg.method
+        when "session/cancel" then cancel(params[:sessionId])
+        when "$/cancel_request" then cancel(@pending.key(params[:requestId]))
+        # Any other notification is ignored — a notification may always be.
+        end
+      end
+
+      # -- methods ---------------------------------------------------------------
+
+      def initialize_result
+        # Reports what this boot mounts, not what the gems can do (docs/acp.md).
+        # v1 advertises no loadSession, no prompt capabilities beyond the
+        # text+resource_link baseline, and no mcp/session subgroups, so the
+        # capabilities object is empty rather than a wall of `false`.
+        { protocolVersion: PROTOCOL_VERSION, agentCapabilities: {}, authMethods: [] }
+      end
+
+      def new_session(id, params)
+        cwd = params[:cwd]
+        mcp = params[:mcpServers]
+        unless cwd.is_a?(String) && !cwd.empty?
+          return enqueue(Wire.error(id: id, code: -32602,
+                                    message: "session/new requires a cwd (an absolute path)"))
+        end
+        unless mcp.is_a?(Array)
+          return enqueue(Wire.error(id: id, code: -32602,
+                                    message: "session/new requires mcpServers (a list, possibly empty)"))
+        end
+
+        # Spawn BEFORE the durable create, so a registry refusal (the agent cap)
+        # cannot leave an orphaned session in the log — create only runs once the
+        # agent exists. cwd does not widen filesystem reach and mcpServers are
+        # not mounted in v1 (docs/acp.md): the profile's floor governs.
+        sid = SecureRandom.hex(6)
+        agent = @ctx[:loop].spawn_agent(session_id: sid)
+        @ctx[:sessions].create(id: sid)
+        @sessions[sid] = agent
+        enqueue(Wire.response(id: id, result: { sessionId: sid }))
+      rescue AgentExists, AgentCapExceeded => e
+        # A registry refusal is this process's business, not the client's fault;
+        # it still deserves an answer rather than a dropped connection.
+        enqueue(Wire.error(id: id, code: -32603, message: e.message))
+      end
+
+      def prompt(request_id, params)
+        sid = params[:sessionId]
+        agent = resolve_agent(sid)
+        unless agent
+          return enqueue(Wire.error(id: request_id, code: -32602, message: "unknown session #{sid.inspect}"))
+        end
+
+        blocks = params[:prompt]
+        unless blocks.is_a?(Array) && !blocks.empty?
+          return enqueue(Wire.error(id: request_id, code: -32602,
+                                    message: "session/prompt requires a non-empty prompt"))
+        end
+
+        text = render_prompt(blocks)
+        if text.empty?
+          # A prompt whose blocks carry nothing we can act on (no text, only
+          # unhandled block types) is invalid params — the fresh and resume
+          # branches both refuse it rather than driving an empty turn.
+          return enqueue(Wire.error(id: request_id, code: -32602,
+                                    message: "session/prompt has no text content to act on"))
+        end
+        if @pending.key?(sid)
+          return enqueue(Wire.error(id: request_id, code: -32600,
+                                    message: "a prompt is already in flight for #{sid}"))
+        end
+
+        @pending[sid] = request_id
+        drive_turn(agent, sid, text)
+      end
+
+      # The pending request stays open for the whole turn (docs/acp.md). The
+      # turn task is rooted on runner_task so a disconnect cannot cancel it; on
+      # completion it answers the pending prompt with the mapped stop reason.
+      # A session whose log holds an open turn resumes it — an editor reopening
+      # a project is the canonical way to meet a turn a killed process left
+      # open — otherwise a fresh run_turn.
+      def drive_turn(agent, sid, text)
+        resuming = @ctx[:loop].resumable?(sid)
+        @runner_task.async do
+          status =
+            if resuming
+              agent.inject(text) # the prompt rides the resumed turn's next step
+              @ctx[:loop].resume_turn(agent)
+            else
+              @ctx[:loop].run_turn(agent, text)
+            end
+          respond_prompt(sid, status)
+        rescue StandardError => e
+          # A turn that raised (a runaway MAX_STEPS overflow, an LLM outage) is
+          # a request that could not complete, not a turn with a sad stop
+          # reason: answer -32603, not a result (docs/acp.md, "Stop reasons").
+          warn "terret-acp: turn failed for #{sid}: #{e.class}: #{e.message}"
+          answer = @pending.delete(sid)
+          enqueue(Wire.error(id: answer, code: -32603, message: "the turn failed: #{e.class}")) if answer
+        end
+      end
+
+      def respond_prompt(sid, status)
+        request_id = @pending.delete(sid) or return
+        reason = stop_reason(status)
+        if reason
+          enqueue(Wire.response(id: request_id, result: { stopReason: reason }))
+        else
+          enqueue(Wire.error(id: request_id, code: -32603, message: "the turn failed"))
+        end
+      end
+
+      # Terret's five turn statuses onto ACP's five stop reasons (docs/acp.md).
+      # nil means "answer a -32603 error, not a result" — only `failed`, which
+      # run_turn raises rather than returns, so it is reached defensively.
+      def stop_reason(status)
+        case status
+        when :completed, :empty then "end_turn"
+        when :cancelled then "cancelled"
+        when :rejected then "refusal"
+        when :failed then nil
+        else "end_turn"
+        end
+      end
+
+      def cancel(sid)
+        agent = sid && (@sessions[sid] || @ctx[:loop].agent("agent-#{sid}"))
+        return unless agent # a cancel for a session we do not know is a no-op
+
+        # Lands on the same Agent#cancel the socket's cancel frame drives; the
+        # turn closes cancelled at its next step boundary and respond_prompt
+        # answers the pending prompt with stopReason "cancelled".
+        agent.cancel
+        # A parked agent cannot reach a boundary until its verdict lands, so a
+        # cancel on one denies the pending approval too, if that row is mounted.
+        if agent.status == :waiting_approval && @ctx.service?(:approvals)
+          @ctx[:approvals].deny_pending!(agent.session_id, reason: "cancelled")
+        end
+      end
+
+      # -- session resolution ----------------------------------------------------
+
+      # This connection's session, or a re-attach: a live agent from a prior
+      # connection, or a durable session resumed and given a fresh agent. The
+      # last is the loadSession story done through session/prompt (docs/acp.md).
+      def resolve_agent(sid)
+        return nil unless sid.is_a?(String)
+        return @sessions[sid] if @sessions.key?(sid)
+
+        if (live = @ctx[:loop].agent("agent-#{sid}"))
+          return @sessions[sid] = live
+        end
+        return nil unless @ctx[:sessions].session_ids.include?(sid)
+
+        @ctx[:sessions].resume(sid)
+        @sessions[sid] = @ctx[:loop].spawn_agent(session_id: sid)
+      rescue AgentExists
+        @sessions[sid] = @ctx[:loop].agent("agent-#{sid}") # a racing spawn won; use it
+      end
+
+      # -- outbound: session/event -> session/update -----------------------------
+
+      def project(ev)
+        return unless @sessions.key?(ev.session_id)
+
+        update =
+          case ev.type
+          when "assistant/chunk"
+            { sessionUpdate: "agent_message_chunk",
+              content: text_block(ev.payload[:text]) }
+          when "tool/call"
+            announce(ev.payload[:id])
+            { sessionUpdate: "tool_call", toolCallId: ev.payload[:id],
+              title: ev.payload[:name].to_s, kind: tool_kind(ev.payload[:name]),
+              status: "pending" }
+          when "tool/result"
+            id = ev.payload[:id]
+            # On the resume path complete_dangling can append a tool/result for a
+            # call whose tool/call was already durable before the crash, so this
+            # connection never announced it. A bare tool_call_update for an
+            # unannounced id is a malformed stream to the editor — synthesize the
+            # opening tool_call (pending) first, in order, ahead of the update.
+            synthesize_tool_call(ev.session_id, id) unless @announced[id]
+            failed = !ev.payload[:error].nil?
+            { sessionUpdate: "tool_call_update", toolCallId: id,
+              status: failed ? "failed" : "completed",
+              content: tool_content(ev.payload[:error] || ev.payload[:content]) }
+          end
+        # There is no thinking part in Terret's LLM vocabulary — Text, ToolCall,
+        # ToolResult and nothing else — so agent_thought_chunk has no source and
+        # is never emitted. The other unmapped variants (plan, user_message_chunk,
+        # the *_update family) have no Terret consumer either. See docs/acp.md.
+        return unless update
+
+        notify(ev.session_id, update)
+      rescue StandardError => e
+        # The synthesize lookup reads the log and could raise; a projection fault
+        # must never surface into Sessions#append (emit isolates it too, but this
+        # names the session).
+        warn "terret-acp: projection failed for #{ev.session_id}: #{e.class}: #{e.message}"
+      end
+
+      def announce(id) = @announced[id] = true
+
+      # Emit the opening tool_call for a call whose id this connection has not
+      # announced, reading its name from the log. Ordered ahead of the caller's
+      # tool_call_update because both go through the one FIFO queue.
+      def synthesize_tool_call(sid, id)
+        name = tool_name_for(sid, id)
+        announce(id)
+        notify(sid, { sessionUpdate: "tool_call", toolCallId: id, title: name.to_s,
+                      kind: tool_kind(name), status: "pending" })
+      end
+
+      def tool_name_for(sid, id)
+        @ctx[:sessions].fetch(sid).events.reverse_each
+                       .find { |e| e.type == "tool/call" && e.payload[:id] == id }
+                       &.payload&.[](:name)
+      end
+
+      def tool_kind(name)
+        name = name.to_s
+        return TOOL_KINDS[name] if TOOL_KINDS.key?(name)
+        return "execute" if name.start_with?("job_", "terminal_")
+
+        "other"
+      end
+
+      def text_block(text) = { type: "text", text: text.to_s }
+
+      def tool_content(body)
+        return [] if body.nil?
+
+        [{ type: "content", content: text_block(body) }]
+      end
+
+      # Baseline blocks are text and resource_link (docs/acp.md). Terret's
+      # user/message is plain text, so a resource_link folds into the text as a
+      # named reference; unknown block types are skipped leniently.
+      def render_prompt(blocks)
+        blocks.filter_map do |block|
+          next unless block.is_a?(Hash)
+
+          case block[:type]
+          when "text" then block[:text]
+          when "resource_link" then "#{block[:name] || block[:uri]} (#{block[:uri]})"
+          end
+        end.join("\n")
+      end
+
+      def notify(sid, update)
+        enqueue(Wire.notification(method: "session/update",
+                                  params: { sessionId: sid, update: update }))
+      end
+    end
+  end
+end

data/lib/terret/acp/service.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "server"
+
+module Terret
+  module ACP
+    # ctx[:acp] — the ACP interface plugin (docs/acp.md). Like terret-ws it is
+    # an interface with no session vocabulary of its own: it mounts through the
+    # loader, injects the two seams it drives, and disposes clean. The second
+    # interface on a completely different transport, built out of the same
+    # seams with no change to core, is what turns "the interface is not
+    # privileged" (plan §9.1) from a claim into evidence.
+    class Service < Hames::Service
+      service_key :acp
+      inject :sessions, :loop
+      # ACP over stdio has no config surface — the transport is the client's
+      # own stdin/stdout, auth is the process boundary (authMethods is empty),
+      # and everything a turn may do is the profile's floor, not this row's.
+      # An empty schema is a declaration, so doctor calls it ok rather than
+      # unschema'd (docs/composition.md §9).
+      config_schema({})
+
+      def start(ctx)
+        @ctx = ctx
+      end
+
+      # Serve ACP over a duplex IO pair until the input closes. stdout carries
+      # ONLY ACP frames; logs go to stderr (docs/acp.md), which is where Ruby's
+      # warn already writes — so a stray `puts` in a mounted plugin is the one
+      # thing that corrupts this stream. The IO pair is injectable exactly like
+      # the openrouter adapter's transport: tests drive it over an in-memory
+      # pipe, `trt acp` passes $stdin/$stdout.
+      #
+      # One reactor: the read loop parks the fiber, and turn tasks root on the
+      # top-level task so a disconnect never cancels a turn in flight. Blocks
+      # until the input reaches EOF.
+      def serve(input: $stdin, output: $stdout)
+        require "async"
+        Async do |task|
+          Server.new(ctx: @ctx, input: input, output: output, runner_task: task).run
+        end
+      end
+    end
+  end
+end

data/lib/terret/acp/wire.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Terret
+  module ACP
+    # JSON-RPC 2.0 framing for ACP v1 (docs/acp.md, "Framing"). The transport
+    # is newline-delimited — one JSON object per line, no LSP `Content-Length`
+    # headers — so the Server reads a line and hands it here, and every frame
+    # this builds is a single line: JSON.generate escapes an embedded newline
+    # to `\n`, which is what keeps one frame from splitting into two.
+    #
+    # A codec, not a socket: it holds no IO. The Server owns the duplex pair
+    # (input.gets / output.write) exactly as terret-ws's Connection owns its
+    # injectable io. stdlib json only — the interface gems carry their own
+    # transport deps, the kernel and this codec carry none.
+    module Wire
+      JSONRPC = "2.0"
+
+      # A decoded inbound frame, already classified. `kind` is one of
+      # :request, :notification, :response, :invalid, :parse_error — the
+      # Server switches on it before it ever looks at `method`, so a garbage
+      # line becomes an error frame instead of a crashed read loop.
+      Message = Data.define(:kind, :id, :method, :params, :result, :error) do
+        def request? = kind == :request
+        def notification? = kind == :notification
+      end
+
+      module_function
+
+      def request(id:, method:, params: nil)
+        h = { jsonrpc: JSONRPC, id: id, method: method }
+        h[:params] = params unless params.nil?
+        frame(h)
+      end
+
+      def notification(method:, params: nil)
+        h = { jsonrpc: JSONRPC, method: method }
+        h[:params] = params unless params.nil?
+        frame(h)
+      end
+
+      def response(id:, result:)
+        frame(jsonrpc: JSONRPC, id: id, result: result)
+      end
+
+      def error(id:, code:, message:, data: nil)
+        err = { code: code, message: message }
+        err[:data] = data unless data.nil?
+        frame(jsonrpc: JSONRPC, id: id, error: err)
+      end
+
+      # One line, guaranteed. JSON.generate never emits a raw newline (it
+      # escapes one inside a string), so the guard is belt-and-braces against a
+      # future generator swap rather than something reachable today.
+      def frame(hash)
+        line = JSON.generate(hash)
+        raise ArgumentError, "a frame must not contain an embedded newline" if line.include?("\n")
+
+        line
+      end
+
+      # Never raises: a malformed line from an editor gets an answer, not a
+      # dropped agent. The Server maps :parse_error to -32700 and :invalid to
+      # -32600. A response arriving here (we send no client requests, so we
+      # expect none) is classified rather than mistaken for a request.
+      def decode(line)
+        parsed = begin
+          JSON.parse(line, symbolize_names: true)
+        rescue JSON::ParserError
+          return blank(:parse_error)
+        end
+        return blank(:invalid) unless parsed.is_a?(Hash)
+
+        if parsed.key?(:method)
+          kind = parsed.key?(:id) ? :request : :notification
+          Message.new(kind: kind, id: parsed[:id], method: parsed[:method],
+                      params: parsed[:params], result: nil, error: nil)
+        elsif parsed.key?(:result) || parsed.key?(:error)
+          Message.new(kind: :response, id: parsed[:id], method: nil, params: nil,
+                      result: parsed[:result], error: parsed[:error])
+        else
+          Message.new(kind: :invalid, id: parsed[:id], method: nil, params: nil,
+                      result: nil, error: nil)
+        end
+      end
+
+      def blank(kind)
+        Message.new(kind: kind, id: nil, method: nil, params: nil, result: nil, error: nil)
+      end
+    end
+  end
+end

data/lib/terret/acp.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+begin
+  require "terret"
+rescue LoadError
+  require_relative "../../../terret-core/lib/terret" # monorepo path source
+end
+
+require_relative "acp/wire"
+require_relative "acp/bounded_queue"
+require_relative "acp/server"
+require_relative "acp/service"

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: terret-acp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Obie Fernandez
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: terret-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: 'The second interface (plan §9.1): an ACP v1 server so an editor can
+  drive a Terret agent over JSON-RPC 2.0 on stdio. Newline-delimited framing, session/new
+  spawns a durable agent, session/prompt pends the whole turn, session/update notifications
+  projected from the session log. Consumes the same two seams the socket does with
+  no change to core, which is the standing proof that the interface is not privileged.
+  Zero runtime dependencies beyond stdlib json.'
+email:
+- obiefernandez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/terret/acp.rb
+- lib/terret/acp/bounded_queue.rb
+- lib/terret/acp/server.rb
+- lib/terret/acp/service.rb
+- lib/terret/acp/wire.rb
+homepage: https://terret.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://terret.org
+  source_code_uri: https://github.com/terret-org/terret
+  bug_tracker_uri: https://github.com/terret-org/terret/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Agent Client Protocol server for the Terret agent harness
+test_files: []