#Agent Core SDK CLI

The totto2727/agent-core-sdk/cli package runs an agent CLI as a child process, writes its stdin, decodes ordered JSONL events, captures failed-exit stderr, and reports the process outcome.

This document is canonical src/cli/README.mbt.md.

#Usage

Install the published module and import its CLI package:

moon add totto2727/agent-core-sdk@0.1.2

///|
struct Event {
  message : String
} derive(FromJson)

///|
async test "run streams a JSONL event" {
  let result = @cli.run(
    @cli.Invocation::new(
      command="/usr/bin/printf",
      arguments=["{\"message\":\"Hello\"}\\n"],
      input="",
    ),
    fn(event : Event) raise {
      assert_eq(event.message, "Hello")
      true
    },
  )
  debug_inspect(result, content="Completed")
}

The callback receives events in stdout order. Return true to continue streaming or false to terminate the child and receive Stopped.

Declare the package in a consumer's moon.pkg:

import {
  "totto2727/agent-core-sdk/cli",
}

#Key features

Invocation carries the command, arguments, environment overrides, inheritance policy, and stdin for one child process.
run decodes each JSONL line into the caller's FromJson type and invokes the callback once per event.
RunResult reports Completed, callback-requested Stopped, or Failed(code~, stderr~) for a nonzero exit.
Malformed JSONL and events that do not match the requested type raise AgentCliError::InvalidJson after child resources are cleaned up.
Provider SDKs remain responsible for provider-specific command arguments, event types, and turn aggregation.

#Prerequisites

MoonBit: Install the MoonBit toolchain and moon command.
Agent CLI: Make the executable named by Invocation.command available to the process environment.

#Setup

Add the module to a MoonBit project.

moon add totto2727/agent-core-sdk@0.1.2

Import totto2727/agent-core-sdk/cli from the package that invokes the agent CLI.
Construct an Invocation with the child command and input, then await run with an event decoder and callback.

#API

Mooncakes totto2727/agent-core-sdk/cli API reference

#Development

See AGENTS.md for repository structure, package ownership, target policy, and development commands.

#License

MIT

This README was generated from the share-artifact skill and README template.

AgentCliError

source

pub 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 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.

command and arguments select the executable and its arguments. environment adds or replaces variables, and inherit_environment controls whether the child receives the parent environment. input is written to the child's standard input before events are consumed.

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 with optional environment configuration.

The default inherits the parent environment and applies no extra variables. Use inherit_environment=false with an explicit PATH when the child must run with a deterministic environment.

RunResult

source

pub 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.

Completed means the child exited with status zero, Stopped means the callback returned false, and Failed contains a nonzero exit code and the captured standard error text.

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.

A typical call is run(Invocation::new(command="agent", arguments=["run"],input="Hello"), async fn(event : Event) { handle(event); true }) where Event derives FromJson.