ClaudeWrapper.DuplexSession.Adapter behaviour (ClaudeWrapper v0.15.2)

Copy Markdown View Source

Transport seam for ClaudeWrapper.DuplexSession.

A DuplexSession drives the claude subprocess through exactly three active operations -- open the transport, write a line to it, close it -- and consumes inbound message shapes delivered to its own process mailbox:

  • {handle, {:data, chunk}} -- raw stdout bytes
  • {handle, {:exit_status, code}} -- the subprocess exited
  • {:EXIT, handle, reason} -- the transport process exited

The optional Forcola adapter also sends acknowledged {handle, {:data, chunk, ref}} and {handle, {:stderr, line, ref}} messages, followed by {handle, {:terminal, evidence}}. The session acknowledges each line before the adapter requests another.

where handle is the value the adapter's open/1 returned (and which the session stores as its transport handle). An adapter implements the three operations; the inbound side is just a matter of sending those message shapes to the :owner given at open/1.

Two implementations ship:

Summary

Types

handle()

The opaque transport handle returned by open/1.

open_opts()

Options passed to open/1. Always carries

Callbacks

ack(handle, reference)

Optionally acknowledge a pull-delivered line after processing it.

close(handle)

Shut the transport down. Idempotent; the handle may already be dead.

command(handle, iodata)

Write iodata (one NDJSON line, newline included) to the transport.

open(open_opts)

Start the transport. Returns an opaque handle the session stores.

shutdown(handle)

Optionally shut down while retaining structured transport evidence.

Types

handle()

@type handle() :: term()

The opaque transport handle returned by open/1.

open_opts()

@type open_opts() :: keyword()

Options passed to open/1. Always carries:

  • :config -- the ClaudeWrapper.Config.t/0
  • :args -- the resolved CLI argument list
  • :owner -- the session pid that inbound messages are sent to

Adapter-specific keys (from the session's :adapter_opts) are merged in.

Callbacks

ack(handle, reference)

(optional) 
@callback ack(handle(), reference()) :: :ok

Optionally acknowledge a pull-delivered line after processing it.

close(handle)

@callback close(handle()) :: :ok

Shut the transport down. Idempotent; the handle may already be dead.

command(handle, iodata)

@callback command(handle(), iodata()) :: :ok | {:error, term()}

Write iodata (one NDJSON line, newline included) to the transport.

open(open_opts)

@callback open(open_opts()) :: {:ok, handle()} | {:error, term()}

Start the transport. Returns an opaque handle the session stores.

shutdown(handle)

(optional) 
@callback shutdown(handle()) :: {:ok, term()} | {:error, term()}

Optionally shut down while retaining structured transport evidence.