/ 
Langertha-Raider-0.504
/ Langertha::Raider::Hall::ACP

NAME

Langertha::Raider::Hall::ACP - Internal ACP (Agent Client Protocol) adapter that exposes the hall over TCP

VERSION

version 0.504

DESCRIPTION

Internal module. Its interface may change without notice.

Minimal ACP server. Speaks JSON-RPC 2.0 line-framed over TCP. Clients that speak ACP over TCP (raider acp, Langertha::Raider::ACP::Client) connect to the configured port and drive raiders through the hall. An editor that starts its agent as a command over stdio needs the stdio server of ADR 0010, which does not exist yet.

Supported methods

  • initialize — handshake. Returns protocolVersion and agentCapabilities (promptCapabilities: image=false, audio=false, embeddedContext=false).

  • session/new — create a session bound to a raider slot. Params: { cwd, mcpServers?, raiderName? }. If raiderName is given it selects the configured raider; otherwise the first entry in .raider-hall.yml is used.

  • session/prompt — spawn the raider with the user turn's text content, stream session/update notifications from the hall event bus, return { stopReason } when the raider finishes. A run that completes ends end_turn, a cancelled run ends cancelled, and a failed run (an engine error, a crash, a run that ended without a result) ends session/prompt as a JSON-RPC error (code -32000), not as a normal answer: its error text rides in the JSON-RPC error message and is never streamed as an agent_message_chunk, so an editor tells a broken run apart from a reply. All prompts of an ACP session run in one raider session, bound as acp:SESSION until the client disconnects (see "session_bindings" in Langertha::Raider::Hall). A prompt that has to wait -- its 1name slot or its session is busy -- gets no answer until its run has started and ended; then it is answered like any other -- end_turn, cancelled or a JSON-RPC error -- also when the hall had to start that run without the session (hall.session_error). A prompt whose mission the hall refuses (raider.refused, see "EVENT BUS" in Langertha::Raider::Hall) -- at once or when it is pulled from its queue -- ends as JSON-RPC error -32000 with the refusal's text; nothing ran. The ACP stop reason refusal is not used for it: in ACP it means the model refused.

  • session/cancel — cancel the running raider's run with a SIGINT ("cancel_raider" in Langertha::Raider::Hall): it ends the run as cancelled, and its prompt is answered cancelled. A raider the signal does not end gets SIGTERM, then SIGKILL, each after the hall's cancel_grace. Prompts still waiting are answered cancelled and never run.

Asking the client (session/request_permission)

A tool call the raider's permission policy asks about (ADR 0021: the mode default, plan, ... without a rule that decides) is put to the ACP client as the agent-to-client request session/request_permission (ACP v1, https://agentclientprotocol.com/protocol/tool-calls): sessionId, a toolCall update (toolCallId, title, kind, status pending, rawInput, the reason as content) and the options allow_once ("Allow once"), allow_always ("Allow for this session: RULE", only when a rule can name the call) and reject_once. allow_once runs this call; allow_always adds the rule as a session rule of the raider (as the REPL's "yes, for this session"); reject_once, reject_always, the outcome cancelled, an unknown option, an error, a closed connection, a cancelled turn (session/cancel) and no answer within the hall's "permission_timeout" in Langertha::Raider::Hall (default 120 s) all refuse the call -- the model is told, the run goes on. Nothing allows by default. The raider asks over a per-run socket (Langertha::Raider::Hall::PermissionChannel); the adapter registers itself per session with "register_permission_handler" in Langertha::Raider::Hall. The responses of the client are matched to the question by id in the dispatch loop. initialize announces nothing for this: asking is the agent's right in ACP.

Features intentionally omitted in this first cut: authentication, filesystem push-edits, embedded context resources, audio/image content blocks. Calls unknown to this adapter return JSON-RPC error -32601 method not found.

SUPPORT

Issues

Please report bugs and feature requests at https://github.com/Getty/langertha-raider/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

https://raudssus.de/