READMEcolmugx/acp/client does not have a README file
#ClientElicitationCompleteHandler
#ClientElicitationFormHandler
Typed elicitation callbacks. Form and URL requests carry their
mode-specific payloads; completion is a separate notification observer.
#ClientElicitationUrlHandler
#ClientNotificationBroker
A one-shot typed notification transport. Notifications have no reply,
and this facade deliberately keeps this port synchronous: a runtime may
accept the immutable notification intent into a bounded queue (or fail
fast); Ok does not claim that transport I/O has completed.
#ClientProgram
A pure Reader composition program for one caller-owned environment.
#ClientReadTextFileHandler
Typed filesystem callbacks. Read and write remain independent services
so each capability can be derived without a manually supplied flag.
#ClientRequestBroker
A one-shot typed request transport. It owns no request identifiers or
connection state; those remain with the runtime that implements it.
#ClientRequestPermissionHandler
A typed handler for Agent permission requests received by the Client.
#ClientSessionUpdateHandler
A typed observer for Agent session/update notifications received by the
Client.
#ClientTerminalCreateHandler
Typed terminal callbacks. Terminal support is all-or-nothing at the
service boundary, matching the five-operation ACP surface.
#ClientTerminalKillHandler
#ClientTerminalOutputHandler
#ClientTerminalReleaseHandler
#ClientTerminalWaitForExitHandler
type ClientTerminalWaitForExitHandler = async (TerminalWaitForExitParams) -> TerminalWaitForExitResult#ClientWriteTextFileHandler
#ClientAdapterError
Invalid adapter composition or a completion whose closed-union variant or
request id does not match the admitted operation. Duplicate/late task
events are owned by the connection reducer and are not shadowed here.
#ClientConnectionError
pub(all) suberror ClientConnectionError {
ClientConnectionUnsupportedVersion(method_name~ : String, version~ : Int)
ClientConnectionUnavailable(method_name~ : String)
ClientConnectionCancelled(method_name~ : String)
ClientConnectionBrokerFailure(method_name~ : String)
ClientConnectionReplyMismatch(method_name~ : String, expected~ : String, actual~ : String)
} derive(Eq, Debug)Explicit failures crossing the Client-to-Agent typed connection facade.
Runtime adapters may return these values from negotiated capability gates
or transport cancellation; the facade never converts them into success.
#ClientAdapterAdmission
pub(all) enum ClientAdapterAdmission {
Immediate(ClientAdapterStep)
Invoke(state~ : ClientAdapterState, invocation~ : ClientAdapterInvocation)
}Admission is synchronous and pure. Only Invoke crosses the async
handler boundary; Immediate already contains its complete owner-loop
state transition and output.
#ClientAdapterCommand
pub(all) enum ClientAdapterCommand {
CancelRequest(request_id~ : RequestId)
TraceError(method_name~ : String, error~ : JsonRpcError)
} derive(Eq, Debug)Runtime intents emitted by the Client adapter. These values are data
only; cancellation itself is owned by the connection/reducer runtime.
#ClientAdapterCompletion
pub(all) enum ClientAdapterCompletion {
RequestPermissionCompleted(id~ : RequestId, result~ : Result[RequestPermissionResponse, HandlerError])
FsReadTextFileCompleted(id~ : RequestId, result~ : Result[ReadTextFileResult, HandlerError])
FsWriteTextFileCompleted(id~ : RequestId, result~ : Result[WriteTextFileResult, HandlerError])
TerminalCreateCompleted(id~ : RequestId, result~ : Result[TerminalCreateResult, HandlerError])
TerminalOutputCompleted(id~ : RequestId, result~ : Result[TerminalOutputResult, HandlerError])
TerminalWaitForExitCompleted(id~ : RequestId, result~ : Result[TerminalWaitForExitResult, HandlerError])
TerminalKillCompleted(id~ : RequestId, result~ : Result[TerminalKillResult, HandlerError])
TerminalReleaseCompleted(id~ : RequestId, result~ : Result[TerminalReleaseResult, HandlerError])
ElicitationCreateCompleted(id~ : RequestId, result~ : Result[ElicitationCreateResult, HandlerError])
SessionUpdateCompleted(result~ : Result[Unit, HandlerError])
ElicitationCompleteCompleted(result~ : Result[Unit, HandlerError])
} derive(Eq, Debug)Typed completion returned by the async handler phase. No state update or
response is produced until the owner loop passes this value to
client_adapter_complete.
#ClientAdapterInvocation
pub(all) enum ClientAdapterInvocation {
RequestPermissionInvocation(id~ : RequestId, params~ : RequestPermissionRequest)
FsReadTextFileInvocation(id~ : RequestId, params~ : ReadTextFileParams)
FsWriteTextFileInvocation(id~ : RequestId, params~ : WriteTextFileParams)
TerminalCreateInvocation(id~ : RequestId, params~ : TerminalCreateParams)
TerminalOutputInvocation(id~ : RequestId, params~ : TerminalOutputParams)
TerminalWaitForExitInvocation(id~ : RequestId, params~ : TerminalWaitForExitParams)
TerminalKillInvocation(id~ : RequestId, params~ : TerminalKillParams)
TerminalReleaseInvocation(id~ : RequestId, params~ : TerminalReleaseParams)
ElicitationCreateInvocation(id~ : RequestId, params~ : ElicitationCreateParams)
SessionUpdateInvocation(params~ : SessionUpdateParams)
ElicitationCompleteInvocation(params~ : ElicitationCompleteParams)
} derive(Eq, Debug)One immutable typed operation admitted by the Client adapter. The
invocation carries protocol data only; connection state remains with the
owner loop that supplied the admission state.
#ClientAdapterOutput
pub(all) enum ClientAdapterOutput {
Response(JsonRpcResponse)
Command(ClientAdapterCommand)
} derive(Eq, Debug)Wire responses and runtime trace intents produced by one adapter step.
#ClientAdapterState
Adapter state contains only the protocol lifecycle and negotiated
capabilities. Request correlation and task tokens remain in the
connection/reducer owner; the adapter does not mirror them.
#ClientAdapterState::protocol
#ClientAdapterStep
pub(all) struct ClientAdapterStep {
state : ClientAdapterState
outputs : Array[ClientAdapterOutput]
} derive(Eq, Debug)The explicit state/output result of an admission or completion step.
#ClientConnection
pub struct ClientConnection {
request_broker : async (AgentRequest) -> Result[ClientReply, ClientConnectionError]
notification_broker : (AgentNotification) -> Result[Unit, ClientConnectionError]
}Opaque typed Client connection facade. Only immutable broker closures are
retained; no mutable protocol state, request-id table, capability flags,
queue, task, global, or service locator is stored here.
#ClientConnection::authenticate
async fn ClientConnection::authenticate(self : ClientConnection, params : AuthenticateParams) -> AuthenticateResult raise ClientConnectionError#ClientConnection::cancel
fn ClientConnection::cancel(self : ClientConnection, params : CancelParams) -> Unit raise ClientConnectionErrorEmit the stable session/cancel notification. No response is synthesized.
#ClientConnection::cancel_request
fn ClientConnection::cancel_request(self : ClientConnection, request_id : RequestId) -> Unit raise ClientConnectionErrorEmit the bidirectional JSON-RPC cancellation notification. Correlation
identifiers remain typed and are not converted through raw JSON.
#ClientConnection::close_session
async fn ClientConnection::close_session(self : ClientConnection, params : CloseSessionParams) -> CloseSessionResult raise ClientConnectionError#ClientConnection::delete_session
async fn ClientConnection::delete_session(self : ClientConnection, params : DeleteSessionParams) -> DeleteSessionResult raise ClientConnectionError#ClientConnection::initialize
async fn ClientConnection::initialize(self : ClientConnection, params : InitializeParams) -> InitializeResult raise ClientConnectionError#ClientConnection::list_sessions
async fn ClientConnection::list_sessions(self : ClientConnection, params : ListSessionsParams) -> ListSessionsResult raise ClientConnectionError#ClientConnection::load_session
async fn ClientConnection::load_session(self : ClientConnection, params : LoadSessionParams) -> LoadSessionResult raise ClientConnectionError#ClientConnection::logout
async fn ClientConnection::logout(self : ClientConnection, params : LogoutParams) -> LogoutResult raise ClientConnectionError#ClientConnection::new_session
async fn ClientConnection::new_session(self : ClientConnection, params : NewSessionParams) -> NewSessionResult raise ClientConnectionError#ClientConnection::prompt
async fn ClientConnection::prompt(self : ClientConnection, params : PromptParams) -> PromptResult raise ClientConnectionError#ClientConnection::resume_session
async fn ClientConnection::resume_session(self : ClientConnection, params : ResumeSessionParams) -> ResumeSessionResult raise ClientConnectionError#ClientConnection::set_config_option
async fn ClientConnection::set_config_option(self : ClientConnection, params : SetSessionConfigOptionParams) -> SetSessionConfigOptionResult raise ClientConnectionError#ClientConnection::set_mode
async fn ClientConnection::set_mode(self : ClientConnection, params : SetSessionModeParams) -> SetSessionModeResult raise ClientConnectionError#ClientElicitationService
pub struct ClientElicitationService {
form_handler : async (ElicitationFormParams) -> ElicitationCreateResult?
url_handler : async (ElicitationUrlParams) -> ElicitationCreateResult?
complete_handler : async (ElicitationCompleteParams) -> Unit?
}Immutable elicitation service. URL support requires completion handling;
this prevents advertising a flow that cannot consume its completion event.
#ClientEndpoint
pub struct ClientEndpoint {
info : Implementation
session : ClientSessionService
file_system : ClientFileSystemService?
terminal : ClientTerminalService?
elicitation : ClientElicitationService?
capabilities : ClientCapabilities
}An opaque, fully validated Client endpoint. It owns immutable services
and derived initialization capabilities, never connection-scoped state.
#ClientEndpoint::capabilities
Return capabilities derived exclusively from the supplied services.
#ClientEndpoint::elicitation_complete
async fn ClientEndpoint::elicitation_complete(self : ClientEndpoint, params : ElicitationCompleteParams) -> Unit raise HandlerErrorObserve elicitation/complete notifications.
#ClientEndpoint::elicitation_form
async fn ClientEndpoint::elicitation_form(self : ClientEndpoint, params : ElicitationFormParams) -> ElicitationCreateResult raise HandlerErrorInvoke form-mode elicitation/create.
#ClientEndpoint::elicitation_url
async fn ClientEndpoint::elicitation_url(self : ClientEndpoint, params : ElicitationUrlParams) -> ElicitationCreateResult raise HandlerErrorInvoke URL-mode elicitation/create.
#ClientEndpoint::info
Return the immutable implementation information used for initialization.
#ClientEndpoint::read_text_file
async fn ClientEndpoint::read_text_file(self : ClientEndpoint, params : ReadTextFileParams) -> ReadTextFileResult raise HandlerErrorInvoke the optional fs/read_text_file handler.
#ClientEndpoint::request_permission
async fn ClientEndpoint::request_permission(self : ClientEndpoint, request : RequestPermissionRequest) -> RequestPermissionResponse raise HandlerErrorDeliver a permission request to the Client handler.
#ClientEndpoint::session_update
async fn ClientEndpoint::session_update(self : ClientEndpoint, params : SessionUpdateParams) -> Unit raise HandlerErrorDeliver a session/update notification to the Client observer.
#ClientEndpoint::terminal_create
async fn ClientEndpoint::terminal_create(self : ClientEndpoint, params : TerminalCreateParams) -> TerminalCreateResult raise HandlerErrorInvoke terminal/create on the complete terminal service.
#ClientEndpoint::terminal_kill
async fn ClientEndpoint::terminal_kill(self : ClientEndpoint, params : TerminalKillParams) -> TerminalKillResult raise HandlerErrorInvoke terminal/kill on the complete terminal service.
#ClientEndpoint::terminal_output
async fn ClientEndpoint::terminal_output(self : ClientEndpoint, params : TerminalOutputParams) -> TerminalOutputResult raise HandlerErrorInvoke terminal/output on the complete terminal service.
#ClientEndpoint::terminal_release
async fn ClientEndpoint::terminal_release(self : ClientEndpoint, params : TerminalReleaseParams) -> TerminalReleaseResult raise HandlerErrorInvoke terminal/release on the complete terminal service.
#ClientEndpoint::terminal_wait_for_exit
async fn ClientEndpoint::terminal_wait_for_exit(self : ClientEndpoint, params : TerminalWaitForExitParams) -> TerminalWaitForExitResult raise HandlerErrorInvoke terminal/wait_for_exit on the complete terminal service.
#ClientEndpoint::write_text_file
async fn ClientEndpoint::write_text_file(self : ClientEndpoint, params : WriteTextFileParams) -> WriteTextFileResult raise HandlerErrorInvoke the optional fs/write_text_file handler.
#ClientFileSystemService
pub struct ClientFileSystemService {
read_handler : async (ReadTextFileParams) -> ReadTextFileResult?
write_handler : async (WriteTextFileParams) -> WriteTextFileResult?
}Immutable filesystem service. At least one operation must be supplied;
omit the whole service when the Client has no filesystem support.
#ClientReply
pub(all) enum ClientReply {
ClientReplyInitialize(InitializeResult)
ClientReplyAuthenticate(AuthenticateResult)
ClientReplyLogout(LogoutResult)
ClientReplyNewSession(NewSessionResult)
ClientReplyLoadSession(LoadSessionResult)
ClientReplyResumeSession(ResumeSessionResult)
ClientReplyListSessions(ListSessionsResult)
ClientReplyDeleteSession(DeleteSessionResult)
ClientReplyCloseSession(CloseSessionResult)
ClientReplySetMode(SetSessionModeResult)
ClientReplySetConfigOption(SetSessionConfigOptionResult)
ClientReplyPrompt(PromptResult)
} derive(Eq, Debug)The closed set of typed results returned by stable Client-to-Agent
requests. Constructor names are prefixed so this reply union cannot be
confused with the corresponding request constructors.
#ClientReply::method_name
Return the exact request method associated with a typed reply.
#ClientSessionService
pub struct ClientSessionService {
session_update_handler : async (SessionUpdateParams) -> Unit
request_permission_handler : async (RequestPermissionRequest) -> RequestPermissionResponse
}The required baseline Client service. Both callbacks are supplied in one
immutable value; there is no later registration phase.
#ClientSpec
pub struct ClientSpec {
info : Implementation
session : ClientSessionService
file_system : ClientFileSystemService?
terminal : ClientTerminalService?
elicitation : ClientElicitationService?
}The application-owned immutable Client specification consumed by the
Reader composition program.
#ClientTerminalService
pub struct ClientTerminalService {
create_handler : async (TerminalCreateParams) -> TerminalCreateResult
output_handler : async (TerminalOutputParams) -> TerminalOutputResult
wait_for_exit_handler : async (TerminalWaitForExitParams) -> TerminalWaitForExitResult
kill_handler : async (TerminalKillParams) -> TerminalKillResult
release_handler : async (TerminalReleaseParams) -> TerminalReleaseResult
}Immutable complete terminal service. All five callbacks are required by
the signature; an incomplete terminal cannot be represented as a service
value.
#client_adapter_admit
fn client_adapter_admit(state : ClientAdapterState, endpoint : ClientEndpoint, message : JsonRpcMessage) -> ClientAdapterAdmission raise ClientAdapterErrorDecode and admit one Agent-to-Client JSON-RPC message. No endpoint
handler is called by this function.
#client_adapter_cancel_completion
fn client_adapter_cancel_completion(invocation : ClientAdapterInvocation) -> ClientAdapterCompletionSynthesize the typed cancellation completion for one invocation. The
owner loop uses this when it grants an inbound cancellation so the wire id
settles through the normal completion path.
#client_adapter_complete
fn client_adapter_complete(state : ClientAdapterState, invocation : ClientAdapterInvocation, completion : ClientAdapterCompletion) -> ClientAdapterStep raise ClientAdapterErrorComplete one admitted invocation in the owner loop. The adapter checks
only the typed variant and request id; correlation lifetime belongs to the
connection reducer that owns the task table.
#client_adapter_execute
async fn client_adapter_execute(invocation : ClientAdapterInvocation, endpoint : ClientEndpoint) -> ClientAdapterCompletion noraiseExecute exactly one already-admitted typed operation. This phase has no
protocol state and cannot emit a response, trace, queue operation, or
cancellation intent.
#client_adapter_failure_completion
fn client_adapter_failure_completion(invocation : ClientAdapterInvocation) -> ClientAdapterCompletionSynthesize the redacted typed failure completion for one invocation,
following the client_adapter_call convention for unknown failures. The
owner task boundary uses this when async execution itself fails before a
typed completion exists.
#client_adapter_invocation_method_name
The stable wire method name of one typed invocation. Runtime bridges use
it for trace intents only; it never replaces the typed completion.
#client_adapter_state_new
#client_connect_process
async fn client_connect_process(endpoint_factory~ : (RuntimeOutboundChannel[ClientAdapterCompletion]) -> ClientEndpoint, initial_state~ : ClientAdapterState, handlers~ : RuntimeHandlerPort, command~ : String, args? : Array[String], extra_env? : Map[String, String], inherit_env? : Bool, spawned? : (RuntimeProcessPorts) -> Unit, options? : RuntimeOptions, trace? : (RuntimeTraceEvent) -> Unit) -> UnitDrive one spawned agent subprocess as a Client connection over real
process stdio. The child's stdin/stdout become the engine's writer/reader
ports (frames flushed per write), the child's stderr is redirected to this
process's stderr, and diagnostics go to the trace sink (stderr by
default). This is a thin composition of client_runtime_run_with_outbound
over runtime_process_ports; it validates the options fail-fast before
spawning and reuses the same single reader/writer/reducer engine.
Connection scope equals child scope: the composition opens one task group,
spawns the child inside it with no_wait = true, runs the engine, then
closes the child's stdin — the ACP stdio shutdown signal — before group
teardown. A well-behaved agent exits on that EOF and is reaped with its
exit status; an agent that keeps running is gracefully terminated and then
forcefully killed by the async process layer's cancellation handler during
teardown, still inside this call. No detached child and no background
reaper can outlive the returned call.
The client owns that shutdown signal, and closing the child's stdin is
what ends a live interactive session: the engine itself only ends on the
child's stdout EOF, which a well-behaved agent produces after observing
its own stdin EOF. The built-in close therefore runs after the engine has
already ended and cannot serve as the client's proactive shutdown. The
optional spawned callback closes exactly that gap: it receives the real
RuntimeProcessPorts handle right after the spawn succeeds and before
the engine starts, so a composition root (or test driver) can close the
child's stdin, wait for the exit status, or cancel the child at the
moment its session logic decides to. The default is a no-op, so callers
that only consume a self-terminating child keep the previous behavior.
#client_connection
fn client_connection(request_broker~ : async (AgentRequest) -> Result[ClientReply, ClientConnectionError], notification_broker~ : (AgentNotification) -> Result[Unit, ClientConnectionError]) -> ClientConnectionConstruct one immutable Client connection around caller-owned typed
transport ports. This is intentionally a one-shot constructor rather than
a builder or registration API.
#client_elicitation_service
fn client_elicitation_service(form? : async (ElicitationFormParams) -> ElicitationCreateResult, url? : async (ElicitationUrlParams) -> ElicitationCreateResult, complete? : async (ElicitationCompleteParams) -> Unit) -> ClientElicitationService raise ClientCompositionError#client_file_system_service
fn client_file_system_service(read? : async (ReadTextFileParams) -> ReadTextFileResult, write? : async (WriteTextFileParams) -> WriteTextFileResult) -> ClientFileSystemService raise ClientCompositionError#client_program
fn[Env] client_program(spec_program : Reader[Env, Result[ClientSpec, ClientCompositionError]]) -> Reader[Env, Result[ClientEndpoint, ClientCompositionError]]Turn a Reader of a validated Client specification into a one-shot endpoint
program. Each Reader::run derives an isolated endpoint from its Env.
#client_program_from
fn[Env] client_program_from(project : (Env) -> Result[ClientSpec, ClientCompositionError]) -> Reader[Env, Result[ClientEndpoint, ClientCompositionError]]Compose a Client endpoint directly from a caller-owned environment
projection without storing that environment globally.
#client_runtime_owner_port
fn client_runtime_owner_port(endpoint~ : ClientEndpoint, initial_state~ : ClientAdapterState) -> RuntimeOwnerPort[ClientAdapterState, ClientAdapterInvocation, ClientAdapterCompletion, ClientAdapterCommand]Bind one Client endpoint onto the single connection owner-loop engine.
The returned port captures only the immutable endpoint value; every
protocol transition stays inside the engine-owned ClientAdapterState.
There is no second owner loop, shadow pending map, Ref, Mutex, or
builder surface here.
Residual ClientAdapterError values (EndpointMismatch,
UnexpectedMessage, CompletionMismatch) indicate composition or
protocol bugs, but the owner port closures are total by signature. Each
residual is therefore answered with an explicit typed fallback instead of
being swallowed: requests get exactly one internal-error response plus one
trace effect, notifications get one trace effect and no response, and the
owner state is held unchanged. The fallback is visible on the wire and in
the trace sink; it is never a silent success.
#client_runtime_run
async fn client_runtime_run(endpoint~ : ClientEndpoint, initial_state~ : ClientAdapterState, ports~ : RuntimePorts, options~ : RuntimeOptions) -> UnitRun one Client connection on the single native owner-loop engine. This is
a thin composition of connection_runtime_run_owner with
client_runtime_owner_port: it validates the options fail-fast and creates
no connection state of its own.
#client_runtime_run_with_outbound
async fn client_runtime_run_with_outbound(endpoint_factory~ : (RuntimeOutboundChannel[ClientAdapterCompletion]) -> ClientEndpoint, initial_state~ : ClientAdapterState, ports~ : RuntimePorts, options~ : RuntimeOptions) -> UnitRun one Client connection on the single native owner-loop engine with the
engine-level outbound channel handed to the Client endpoint factory. The
factory runs after the connection-local queues and shutdown state exist
and before the loop starts, mirroring the Agent bridge's context factory
timing.
Unlike the Agent side, Client execution takes no separate context: the
endpoint value itself is the only execution seam, and its immutable
service handlers receive parameters only. The factory therefore builds
the endpoint the whole loop will use, letting the composition root
construct service handlers that already captured the channel — typically
by building client_connection_over_channel (in connection/broker) and
closing over it. This package stays independent of the broker package;
the caller decides what the factory builds.
This runner adds no second loop or channel state of its own: it validates
the options fail-fast and reuses the same single reader/writer/reducer
engine as client_runtime_run, whose signature and behavior stay
unchanged.
#client_session_service
fn client_session_service(session_update~ : async (SessionUpdateParams) -> Unit, request_permission~ : async (RequestPermissionRequest) -> RequestPermissionResponse) -> ClientSessionServiceCompose the baseline Client service. Both callbacks are required by the
signature; an incomplete baseline cannot be represented as a service value.
#client_spec
fn client_spec(info~ : Implementation, session~ : ClientSessionService, file_system? : ClientFileSystemService, terminal? : ClientTerminalService, elicitation? : ClientElicitationService) -> Result[ClientSpec, ClientCompositionError]Validate and freeze one Client specification. The baseline session
service is required; optional services are capability sources, never
independent capability flags.
#client_terminal_service
fn client_terminal_service(create~ : async (TerminalCreateParams) -> TerminalCreateResult, output~ : async (TerminalOutputParams) -> TerminalOutputResult, wait_for_exit~ : async (TerminalWaitForExitParams) -> TerminalWaitForExitResult, kill~ : async (TerminalKillParams) -> TerminalKillResult, release~ : async (TerminalReleaseParams) -> TerminalReleaseResult) -> ClientTerminalService
0.1.2
Apache-2.0
Updated 14 hours ago
10 downloadsDependencies
- colmugx/reader0.3.0
- moonbitlang/async0.20.5