Session API

CliSubprocessCore.Session is the normalized long-lived provider session runtime.

It adds provider command construction, stdout/stderr decoding, normalized event sequencing, and subscriber fanout above the shared transport substrate.

Start A Session

ref = make_ref()

{:ok, session, info} =
  CliSubprocessCore.Session.start_session(
    provider: :claude,
    prompt: "Explain the latest failing test",
    subscriber: {self(), ref}
  )

Session Delivery

Tagged subscribers receive:

• {session_event_tag, ref, {:event, %CliSubprocessCore.Event{}}}

Use CliSubprocessCore.Session.extract_event/2 instead of hard-coding the outer mailbox shape.

Transport Snapshot

Session.info/1 exposes transport data through a sanitized public snapshot:

• info.transport.info is recognized by TransportInfo
• info.transport.info omits lower runtime handles such as BEAM pids, OS pids, ports, and transport modules
• info.transport.status reflects the normalized transport status

That keeps the core session API stable while the local session-bearing lane now runs on the Execution Plane-owned process transport seam.

Placement

Pass execution_surface when the provider session should run somewhere other than the default local subprocess:

{:ok, session, info} =
  CliSubprocessCore.Session.start_session(
    provider: :antigravity,
    prompt: "Hello from SSH",
    execution_surface: [
      surface_kind: :ssh_exec,
      transport_options: [destination: "buildbox.example"]
    ]
  )

Lifecycle Calls

The core session API exposes:

• send/2
• send_input/3
• end_input/1
• interrupt/1
• close/1
• subscribe/2
• subscribe/3
• unsubscribe/2
• info/1

These calls delegate to the transport substrate but keep provider-facing semantics and event normalization in the core.