ExternalRuntimeTransport

external_runtime_transport is the shared execution-surface substrate for the Jido runtime stack. It owns the generic execution_surface contract, adapter registry, transport facade, and the built-in :local_subprocess, :ssh_exec, and :guest_bridge families.

The package is intentionally transport-focused. Provider planning, session parsing, approval policy, workspace policy, and other application concerns stay in downstream repos such as cli_subprocess_core.

What This Package Owns

• ExternalRuntimeTransport.ExecutionSurface defines the public placement seam.
• ExternalRuntimeTransport.Transport is the generic run/start facade.
• ExternalRuntimeTransport.ExecutionSurface.Adapter and the internal registry own built-in adapter dispatch.
• the built-in local subprocess, SSH exec, and guest bridge adapters implement the landed transport families.
• ExternalRuntimeTransport.Transport.Options, ExternalRuntimeTransport.Transport.RunOptions, ExternalRuntimeTransport.Transport.RunResult, and ExternalRuntimeTransport.Transport.Info own normalized transport contracts.
• ExternalRuntimeTransport.Command, ExternalRuntimeTransport.ProcessExit, ExternalRuntimeTransport.LineFraming, and ExternalRuntimeTransport.TaskSupport support the substrate itself.

Installation

def deps do
  [
    {:external_runtime_transport, "~> 0.1.0"}
  ]
end

Quick Start

Run a local command through the generic facade:

alias ExternalRuntimeTransport.Command
alias ExternalRuntimeTransport.Transport

{:ok, result} =
  Transport.run(
    Command.new("sh", ["-c", "printf ready"])
  )

IO.inspect(result.stdout)

Move the same command onto SSH without naming an adapter module:

{:ok, result} =
  Transport.run(
    Command.new("hostname"),
    execution_surface: [
      surface_kind: :ssh_exec,
      transport_options: [
        destination: "buildbox.example",
        ssh_user: "deploy",
        port: 22
      ]
    ]
  )

Start a long-lived transport with the same public seam:

ref = make_ref()

{:ok, transport} =
  Transport.start(
    command: Command.new("sh", ["-c", "cat"]),
    subscriber: {self(), ref},
    stdout_mode: :raw,
    stdin_mode: :raw,
    execution_surface: [surface_kind: :local_subprocess]
  )

Execution Surface

The public placement contract is one execution_surface value with these fields:

• contract_version
• surface_kind
• transport_options
• target_id
• lease_ref
• surface_ref
• boundary_class
• observability

The contract does not expose adapter module names. Callers choose placement by describing the surface, and the substrate resolves the built-in adapter internally.

Use ExternalRuntimeTransport.ExecutionSurface.to_map/1 when you need the versioned map projection for JSON-safe boundaries.

Supported built-in surface kinds today are:

• :local_subprocess
• :ssh_exec
• :guest_bridge

Use ExternalRuntimeTransport.ExecutionSurface.capabilities/1, path_semantics/1, remote_surface?/1, and nonlocal_path_surface?/1 when a higher layer needs to reason about the surface generically.

Documentation

• guides/getting-started.md covers the public facade.
• guides/execution-surface-contract.md defines the stable placement seam.
• guides/guest-bridge-contract.md covers the attach contract for :guest_bridge.
• examples/README.md points at runnable placement examples.

Published HexDocs:

https://hexdocs.pm/external_runtime_transport

Oversize Line Recovery

The transport now treats oversized stdout lines as a bounded recovery problem instead of an unbounded buffer-growth bug.

• max_buffer_size remains the steady-state in-memory line buffer and defaults to 1_048_576 bytes.
• oversize_line_chunk_bytes defaults to 131_072 bytes and is used to incrementally recover a large line without letting the framer grow without bound.
• max_recoverable_line_bytes defaults to 16_777_216 bytes and is the hard ceiling for a single recoverable line.
• oversize_line_mode is now :chunk_then_fail and buffer_overflow_mode is intentionally :fatal.

The operational rule is simple: recover the full line while it remains within the configured ceiling, then fail fast with a structured buffer_overflow error once the data-loss boundary is crossed. The transport no longer pretends that silently dropped bytes are a healthy recovery path.