🥮 mooncakes.io
    Sign in

    ears

    Guest-side MoonBit SDK for calling Posoco host capabilities from a program

    posoco
    ears
    moonbit
    sdk
    ptc
    code-mode
    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Last updated
    14 hours ago
    Downloads
    14

    #posoco/ears

    posoco/ears is the SDK for inline code and live code — the MoonBit programs an agent submits directly as tool calls (code bodies and complete .mbtx scripts alike). Guests reach back into the host through it.

    Guest-side MoonBit SDK for calling Posoco host capabilities from a program. The host passes only the run-scoped connection: a guest is a complete .mbtx program — its own imports, its own main — that imports this version-pinned package and calls serve. The host never injects source, so compiler line numbers are the program's own.

    #Guest contract

    import {
      "posoco/ears@0.1.0" @ears,
      "moonbitlang/async",
    }

    async fn main {
      @ears.serve(
        wire=@ears.stdio(),
        run=(ears, input) => {
          let outcome = ears.call("read", { "path": "README.md" })
          if outcome.is_error {
            fail("ears: read failed")
          }
          { "echo": input }
        },
      )
    }

    • Tool failures are values (Outcome::Failure); only transport loss raises. Branch on is_error / match the constructors.
    • Capability decisions stay in the host: the invoke frame declares the allowed names, and Ears::call refuses anything outside it locally (CapabilityDenied) without touching the wire.
    • fail(...) in the guest program becomes a failure result frame (GuestFailed), not a crash.

    #Wire

    Line-framed JSON over stdio, protocol 1: the guest sends hello, request, log, and result frames; the host sends invoke and reply frames. Wire is the transport seam; stdio() is the default.

    Wire

    source
    pub(open) trait Wire {
      async fn send(Self, frame : String) -> Unit
      async fn receive(Self) -> String?
    }

    The guest's line-framed channel contract, abstracted so tests can script a double. send writes one frame; receive returns one frame and None at end of stream.

    Ears

    source
    pub struct Ears {
      // private fields
    }

    Guest handle for calling host capabilities. Constructed by serve with the host-declared capability list; policy denials come back as Failure values, transport loss raises.

    Ears::Ears

    source
    fn Ears::Ears(wire~ : &Wire, allowed~ : Array[String]) -> Ears

    Ears::call

    source
    async fn Ears::call(self : Ears, name : String, arguments : Json) -> Outcome

    Call a host capability by name. CapabilityDenied and ScopeClosed are local Failure values; a disconnected or malformed reply raises.

    Ears::close

    source
    fn Ears::close(self : Ears) -> Unit

    Ears::log

    source
    async fn Ears::log(self : Ears, level? : String, content : String) -> Unit

    Emit a diagnostic to the host. The host decides visibility; this is not output returned to the model. Ignored after close.

    Outcome

    source
    pub(all) enum Outcome {
      Success(content~ : String, structured~ : Json?)
      Failure(code~ : String, content~ : String, structured~ : Json?)
    } derive(Eq, 
    Debug    )

    Wire mirror of the host outcome (protocol 1). Failures are values a guest branches on; only transport loss raises.

    Outcome::equal

    source
    fn Outcome::equal(Outcome, Outcome) -> Bool

    Outcome::from_json

    source
    fn Outcome::from_json(value : Json) -> Outcome raise

    Lenient inverse of to_json: content defaults to empty and structured to absent, so hosts may omit optional fields.

    Outcome::is_error

    source
    fn Outcome::is_error(self : Outcome) -> Bool

    Outcome::not_equal

    source
    fn Outcome::not_equal(x : Outcome, y : Outcome) -> Bool

    Outcome::to_json

    source
    fn Outcome::to_json(self : Outcome) -> Json

    Outcome::to_repr

    source

    StdioWire

    source
    pub struct StdioWire {
    }

    The default stdio transport.

    StdioWire::StdioWire

    source
    fn StdioWire::StdioWire() -> StdioWire

    serve

    source
    async fn serve(wire~ : &Wire, run~ : async (Ears, Json) -> Json) -> Unit

    Guest entry point: greet the host, take the invoke frame, run the guest program once, and emit the result frame. A raised Failure::Failure becomes a failure result; other errors propagate to the runtime.

    stdio

    source
    fn stdio() -> &Wire

    The stdio transport as a &Wire for serve.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io