#MoonBit ACP SDK

#Installation

moon add colmugx/acp

import {
  "colmugx/acp"
}

#Quick Start

#Agent

///|
fn agent_endpoint() -> @acp.AgentEndpoint {
  let spec = @acp.agent_spec(
    info={
      name: "my-agent",
      title: @acp.ProtocolNullable::Omitted,
      version: "0.1.0",
      meta: @acp.ProtocolNullable::Omitted,
    },
    sessions=@acp.agent_session_service(new_session~, prompt~, cancel~),
    support=@acp.agent_support(),
  ).unwrap()
  @acp.agent_endpoint_from_spec(spec)
}

///|
fn agent_initial_state(endpoint : @acp.AgentEndpoint) -> @acp.AgentAdapterState {
  let config : @acp.AgentProtocolConfig = {
    agent_capabilities: @acp.ProtocolNullable::Value(endpoint.capabilities()),
    auth_methods: endpoint.auth_methods(),
    agent_info: @acp.ProtocolNullable::Omitted,
  }
  @acp.agent_adapter_state_new(protocol=@acp.agent_protocol_state_new(config~))
}

///|
async fn new_session(
  _context : @acp.AgentContext,
  _params : @acp.NewSessionParams,
) -> @acp.NewSessionResult {
  {
    session_id: "session-1",
    modes: @acp.ProtocolNullable::Omitted,
    config_options: @acp.ProtocolNullable::Omitted,
    meta: @acp.ProtocolNullable::Omitted,
  }
}

///|
async fn prompt(
  context : @acp.AgentContext,
  _params : @acp.PromptParams,
) -> @acp.PromptResult {
  context.session_update({
    session_id: "session-1",
    update: @acp.SessionUpdate::AgentMessageChunk({
      content: @acp.ContentBlock::Text({
        annotations: @acp.ProtocolNullable::Omitted,
        text: "Working on it...",
        meta: @acp.ProtocolNullable::Omitted,
      }),
      message_id: @acp.ProtocolNullable::Value("message-1"),
      meta: @acp.ProtocolNullable::Omitted,
    }),
    meta: @acp.ProtocolNullable::Omitted,
  })
  let permission = context.request_permission(permission_request())
  let _selected = match permission.outcome {
    @acp.RequestPermissionOutcome::Selected(outcome) => outcome.option_id
    @acp.RequestPermissionOutcome::Cancelled => "cancelled"
  }
  {
    stop_reason: @acp.StopReason::EndTurn,
    meta: @acp.ProtocolNullable::Omitted,
  }
}

///|
async fn cancel(
  _context : @acp.AgentContext,
  _params : @acp.CancelParams,
) -> Unit {
  ()
}

///|
async fn main {
  let endpoint = agent_endpoint()
  @acp.agent_serve_stdio_with_outbound(
    endpoint~,
    context_factory=channel => @acp.agent_context_over_channel(channel~),
    initial_state=agent_initial_state(endpoint),
  )
}

#Client

import {
  "colmugx/acp"
  "colmugx/reader"
  "moonbitlang/async"
  "moonbitlang/async/aqueue" @aqueue
  "moonbitlang/core/json" @json
}

///|
fn client_endpoint(
  updates : Array[@acp.SessionUpdateParams],
) -> @acp.ClientEndpoint {
  let spec = @acp.client_spec(
    info={
      name: "my-client",
      title: @acp.ProtocolNullable::Omitted,
      version: "0.1.0",
      meta: @acp.ProtocolNullable::Omitted,
    },
    session=@acp.client_session_service(
      session_update=async fn(params : @acp.SessionUpdateParams) {
        updates.push(params) // typed update, in wire order
      },
      request_permission=async fn(
        request : @acp.RequestPermissionRequest,
      ) -> @acp.RequestPermissionResponse {
        {
          outcome: @acp.RequestPermissionOutcome::Selected({
            option_id: request.options[0].option_id,
            meta: @acp.ProtocolNullable::Omitted,
          }),
          meta: @acp.ProtocolNullable::Omitted,
        }
      },
    ),
  ).unwrap()
  @reader.Reader::run(@acp.client_program(@reader.Reader::pure(spec)), ()).unwrap()
}

///|
async fn main {
  let updates : Array[@acp.SessionUpdateParams] = []
  let endpoint = client_endpoint(updates)
  let connections : @aqueue.Queue[@acp.ClientConnection] = Queue(kind=Unbounded)
  @async.with_task_group(group => {
    let driver = group.spawn(() => {
      let connection = connections.get()
      connection.initialize({
        protocol_version: 1,
        client_capabilities: @acp.ProtocolNullable::Omitted,
        client_info: @acp.ProtocolNullable::Omitted,
        meta: @acp.ProtocolNullable::Omitted,
      })
      let session = connection.new_session({
        cwd: "/",
        additional_directories: @acp.ProtocolNullable::Omitted,
        mcp_servers: [],
        meta: @acp.ProtocolNullable::Omitted,
      })
      let result = connection.prompt({
        session_id: session.session_id,
        prompt: [],
        meta: @acp.ProtocolNullable::Omitted,
      })
      ignore(result) // result.stop_reason / result.meta carry the typed outcome
    })
    @acp.client_connect_process(
      endpoint_factory=channel => {
        let _ = connections.try_put(
          @acp.client_connection_over_channel(channel~),
        ) catch {
          _ => false
        }
        endpoint
      },
      initial_state=@acp.client_adapter_state_new(
        protocol=@acp.client_protocol_state_ready(
          capabilities=@acp.ProtocolNullable::Value(endpoint.capabilities()),
        ),
      ),
      handlers={
        request: _ => {
          @acp.RuntimeHandlerResult::HandlerSuccess(@json.Json::null())
        },
        notification: _ => (),
        response: _ => (),
        outbound_failure: None,
      },
      command="path/to/agent-binary",
    )
    driver.wait()
  })
  // Fold the recorded updates with the pure consumer fold: chunks sharing
  // one messageId aggregate into one message and tool-call updates patch
  // the tracked call (used end to end in tests/interop/interop_test.mbt).
  let folded = @acp.session_update_fold(known_modes=[])
  println("messages: \{folded.agent_messages.length()}")
}

#Capabilities by Service Presence

• AgentEndpoint::capabilities() comes from the handlers in agent_session_service, the flags in agent_support(), and agent_auth_service when supplied.
• ClientEndpoint::capabilities() comes from client_session_service plus whichever of client_file_system_service, client_terminal_service, and client_elicitation_service you passed to client_spec.

#API Map

#Experimental: ACP v2

#Trace and Diagnostics

#License