#Agent CLI SDK

agent-cli-sdk provides the shared native process lifecycle for MoonBit SDKs that run agent CLIs and consume JSONL events.

Provider SDKs remain responsible for building CLI arguments and environment variables, defining provider-specific event types with FromJson, and aggregating turns. This package owns stdin delivery, ordered JSONL parsing and typed decoding, stderr capture, exit status reporting, callback-requested termination, and cancellation-safe child cleanup.

struct Event {
  message : String
} derive(FromJson)

let result = @agent_cli.run(
  @agent_cli.Invocation::new(
    command="agent",
    arguments=["run", "--format", "json"],
    input="Hello",
  ),
  async fn(event : Event) {
    println(event.message)
    true
  },
)

#
AgentCliError

source

pub(all) suberror AgentCliError {
  InvalidJson(line~ : String, cause~ : String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Errors raised while reading or decoding the JSONL protocol.

#
Invocation

source

pub(all) struct Invocation {
  command : String
  arguments : Array[String]
  environment : Map[String, String]
  inherit_environment : Bool
  input : String
}

A complete invocation of a JSONL-emitting agent CLI.

#
Invocation::new

source

fn Invocation::new(command~ : String, arguments~ : Array[String], input~ : String, environment? : Map[String, String], inherit_environment? : Bool) -> Invocation

Construct an agent CLI invocation.

#
RunResult

source

pub(all) enum RunResult {
  Completed
  Stopped
  Failed(code~ : Int, stderr~ : String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

The process-level outcome of an agent CLI invocation.

#
run

source

async fn[T : @moonbitlang/core/json.FromJson
FromJson] run(invocation : Invocation, on_event : async (T) -> Bool) -> RunResult

Run an agent CLI, write its stdin, and stream decoded JSONL events in order.

Returning false from on_event terminates the child and returns Stopped. A nonzero child exit is returned as Failed; process and callback errors are raised after all child resources have been cleaned up.