🥮 mooncakes.io
README

colmugx/acp/runtime does not have a README file

#
RuntimeCancelOutboundHandler

source
type RuntimeCancelOutboundHandler = async (
RequestId) -> Unit

#
RuntimeOutboundFailureHandler

source
type RuntimeOutboundFailureHandler = async (
RequestId, RuntimeOutboundFailure) -> Unit

#
RuntimeError

source
pub(all) suberror RuntimeError {
  InvalidOptions
  ReaderFailed
  ReaderEmptyChunk
  EventQueueClosed
  EventQueueBackpressure(limit~ : Int)
  WriterQueueClosed
  WriterQueueBackpressure(limit~ : Int)
  WriterFailed
  FramingFailed
  JsonRpcDecodeFailed
  JsonRpcEncodeFailed
  ReducerFailed
  TaskControlMissing
  TaskRequestMismatch
  HandlerFailed
  NotificationFailed
  ResponseHandlerFailed
  OutboundCancelUnavailable
  OutboundCancelFailed
  OutboundCompletionFailed
  CloseCleanupFailed(primary_kind~ : String, cleanup_phase~ : String)
}

Failures at the native runtime boundary.

These errors deliberately carry only failure categories. Peer payloads, prompts, files, tokens, and environment values never enter a trace or an error string produced by the runtime.

#
RuntimeHandlerPort

source

Protocol dispatch seams. They are values rather than globals so tests and composition roots can inject memory or faulting implementations.

#
RuntimeHandlerResult

source
pub(all) enum RuntimeHandlerResult {
  HandlerSuccess(Json)
  HandlerError(
JsonRpcError)
}

Result returned by an inbound request handler. A handler failure is raised through the async port and becomes RuntimeError::HandlerFailed.

#
RuntimeOptions

source
pub(all) struct RuntimeOptions {
  max_frame_bytes : Int
  queue_capacity : Int
  read_chunk_bytes : Int
}

Native runtime bounds. The event and writer queues are intentionally bounded so backpressure is observable instead of becoming unbounded heap growth.

#
RuntimeOutboundFailure

source
pub(all) struct RuntimeOutboundFailure {
  reason : RuntimeOutboundFailureKind
}

Typed completion data for a locally initiated request. The reason is intentionally a category, never a peer payload or arbitrary exception.

#
RuntimeOutboundFailureKind

source
pub(all) enum RuntimeOutboundFailureKind {
  Protocol
  Framing
  Reader
  Writer
  Handler
  Notification
  EndOfInput
  EventQueue
  Runtime
} derive(Eq, 
Debug)

Closed, finite categories for a locally initiated request completion. Arbitrary close strings never cross this boundary.

#
RuntimePorts

source
pub(all) struct RuntimePorts {
  reader : RuntimeReaderPort
  writer : RuntimeWriterPort
  handlers : RuntimeHandlerPort
  cancel_outbound : async (
RequestId) -> Unit?
  trace : (RuntimeTraceEvent) -> Unit
}

All per-connection runtime dependencies.

#
RuntimeProcessPorts

source

The spawned-agent handle handed back with client-side process ports. The ports value drives the single connection engine; child, child_stdin, and child_stdout expose the real moonbitlang/async process seams so a composition root can close the child's stdin (the ACP stdio shutdown signal), wait for the exit status, or cancel the child without any wrapper API duplicating the underlying library.

#
RuntimeReaderPort

source
pub(all) struct RuntimeReaderPort {
  read : async (Int) -> Bytes?
}

Caller-owned asynchronous input seam. None is the only EOF signal.

#
RuntimeTraceEvent

source
pub(all) struct RuntimeTraceEvent {
  direction : String
  phase : String
  request_id : String
  method_name : String
  error_kind : String
}

A redacted runtime trace record. Only routing metadata and a static failure category are exposed to the sink.

#
RuntimeWriterPort

source
pub(all) struct RuntimeWriterPort {
  write : async (Bytes) -> Unit
}

Caller-owned asynchronous output seam. Each call receives one complete newline-delimited frame and must either write all bytes or raise.

#
runtime_default_options

source
fn runtime_default_options() -> RuntimeOptions

#
runtime_libc_write

source
fn runtime_libc_write(fd : Int, buffer : Bytes, count : Int) -> Int

Public wrapper over the raw diagnostics writer so the blackbox suite can prove the byte path against a real pipe. Not exported through the stable facade.

#
runtime_process_ports

source
async fn[G] runtime_process_ports(group : 
TaskGroup[G], handlers~ : RuntimeHandlerPort, command~ : String, args? : Array[String], extra_env? : Map[String, String], inherit_env? : Bool, cancel_outbound? : async (
RequestId) -> Unit?, trace? : (RuntimeTraceEvent) -> Unit) -> RuntimeProcessPorts raise RuntimeError

Construct the client side of one ACP stdio connection over a spawned child process. The child's stdin is the writer target and its stdout is the reader source; the child's stderr is redirected to this process's real stderr so agent diagnostics stay diagnostics and stdout stays pure frames. Both pipe ends are raw, unbuffered @process handles, so every frame write is delivered to the operating system in that call — the pinned flush-per-write discipline, structurally identical to runtime_stdio_ports.

The child is spawned with no_wait = true inside the caller's task group: when the group terminates, the async process layer cancels its wait task, which gracefully terminates the child (then forcefully after its timeout) and reaps it. Child lifetime is therefore bound to the structured concurrency scope that owns the connection — no background reaper loop, no detached process. A well-behaved agent additionally observes the stdin EOF a composition sends through child_stdin.close() before teardown.

Fail-fast mapping (the closed stable RuntimeError set has no process category, so each failure keeps its precise kind in the trace, mirroring the documented closest-category mapping of the outbound channel): an empty command is rejected as InvalidOptions before any OS call; a failed stdout pipe is ReaderFailed and a failed stdin pipe is WriterFailed (the seam that could not be constructed); an OS spawn rejection — including a missing command — is InvalidOptions with trace kind process_spawn_failed, because the caller's process configuration was rejected before any I/O seam ever ran. Every failure is typed and accompanied by one trace event; nothing degrades silently.

#
runtime_request_id_text

source
fn runtime_request_id_text(id : 
RequestId) -> String

#
runtime_stderr_trace

source
fn runtime_stderr_trace(RuntimeTraceEvent) -> Unit

Default trace sink: one write(2) per event to the real standard error. Stdout is never touched here, so the protocol channel keeps carrying newline-delimited ACP frames only. The sink type (RuntimeTraceEvent) -> Unit has no failure channel: when the OS rejects a diagnostics write (for example a closed stderr under a daemon supervisor), the event is dropped without inventing a failure the trace contract cannot carry. Protocol I/O failures stay fully typed at the reader/writer seams.

#
runtime_stdio_ports

source
fn runtime_stdio_ports(trace? : (RuntimeTraceEvent) -> Unit) -> RuntimePorts

Serve the native ACP stdio boundary of this process. The reader reads the real stdin chunk-wise (None is EOF, non-empty chunks only, exactly the RuntimeReaderPort contract). The writer writes each complete newline-delimited frame to the real stdout in one Output::write call: @stdio.Output wraps the raw file descriptor with no userspace buffering (moonbitlang/async/src/stdio/stdio.mbt), so every write is handed to the operating system immediately — the pinned flush-per-write discipline holds structurally because no buffered writer layer exists on this path.

The handler seams exist only for engine runners with an outbound channel. response and outbound_failure are deliberate no-op observers: reply delivery to parked submitters is owned by the engine's outbound channel, never by these callbacks. The legacy dispatch seams (request, notification) abort fail-fast: these ports exist for owner-loop runners, and a legacy handler dispatch through them would silently answer nothing, so it must crash loudly instead.

Diagnostics go to the trace sink, defaulting to stderr. Nothing in this constructor writes to stdout, and it performs no I/O at all beyond binding the process file descriptors.

#
runtime_trace_event

source
fn runtime_trace_event(direction : String, phase : String, request_id : String, method_name : String, error_kind : String) -> RuntimeTraceEvent

#
runtime_trace_stderr_line

source
fn runtime_trace_stderr_line(event : RuntimeTraceEvent) -> String

Render one redacted trace event as exactly one diagnostics line ending in a single newline. The five trace fields keep their fixed order; every value is sanitized first. This renderer is the exact text the default stderr sink writes, which keeps the diagnostics format unit-testable.

#
runtime_validate_options

source
fn runtime_validate_options(options : RuntimeOptions) -> Unit raise RuntimeError

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io