Documentation
¶
Overview ¶
Package relaytool exposes a relay's own bot interface to the ACP agent as self-hosted MCP tools, so the agent can drive the relay from inside a turn.
Why MCP and not an ACP extension ¶
ACP has no agent-initiated message. The agent speaks only inside a turn it was prompted for, and a relay's streaming sink is bound per turn, so an out-of-turn session/update has nowhere to land. But an MCP tool call runs agent→client, which ACP fully supports. The loopback is therefore the correct mechanism and needs no protocol extension.
Identity is the foundation ¶
mcphost binds the session key SERVER-SIDE from the connection's token, so a tool call already knows, unspoofably, which conversation it came from. Nothing here ever accepts a conversation id as a tool argument. Every tool acts on the conversation the call came from, and only that one. Take that guarantee away and `post` becomes a realm-wide megaphone for anything that can prompt-inject the agent.
One implementation, two front ends ¶
Every tool here calls an exported action on *command.Broker — the same method the `!command` a human types calls. There is no second implementation to drift. Adding a tool means adding a Broker action (and, where it makes sense for a human, a `!command` for it), never reaching past the Broker to the relay's Controller.
What is deliberately NOT exposed ¶
A loopback tool must never destroy the turn that is calling it. Two commands fall foul of that rule:
- `stop`. An agent cancelling its own in-flight turn either does nothing or kills the very turn whose tool call asked for it, leaving the tool result undeliverable and the user staring at "superseded". Deferring it to end-of-turn would make it a no-op by definition. There is no coherent reading, so there is no tool.
- `new_session`, in its immediate form. Resetting a session typically cancels the turn in flight, which is the same foot-gun. It IS a coherent thing for an agent to want — "this task is done, clear the context" — so it is exposed as a DEFERRED action: the tool records the intent, and the relay applies it by calling Tools.EndTurn when the turn is over. Same Controller, same implementation, honest timing.
Index ¶
Constants ¶
const ( ToolStatus = "status" ToolListModels = "list_models" ToolSetModel = "set_model" ToolNewSession = "new_session" ToolPost = "post" ToolSchedule = "schedule" ToolListSchedules = "list_schedules" ToolUnschedule = "unschedule" )
Tool names exposed to the agent.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Broker is the shared command surface. Required, and it must
// already have its Controller wired.
Broker *command.Broker
// ConvToken maps the mcphost session key — resolved server-side
// from the connection token — to the Broker's opaque conversation
// token. They are not always the same string: zulip-acp keys
// sessions by conv-id but brokers by conversation KEY, precisely
// so `!new` can replace the former without invalidating the
// latter. Returning ok=false rejects the call, which is what
// happens when the conversation has since been retired.
//
// Nil means the two are identical, which is the simple case.
ConvToken func(sessionKey string) (convToken string, ok bool)
// Logf receives operational messages.
Logf func(format string, args ...any)
}
Config configures a Tools.
type Tool ¶
Tool is one registered tool, kept as data so the set can be built and asserted on without a socket, a subprocess or an MCP handshake.
type Tools ¶
type Tools struct {
// contains filtered or unexported fields
}
Tools is the registered tool set plus the deferred-action state that new_session needs.
func (*Tools) EndTurn ¶
EndTurn applies whatever the agent deferred during the turn that has just finished in convToken. The relay calls it once per completed turn, AFTER the answer has been posted.
Today that is only new_session. It is a method rather than a callback so the relay's turn path has exactly one thing to remember.
func (*Tools) Tools ¶
Tools builds the tool set as data, so it can be exercised without a socket, a subprocess or an MCP handshake.
Capability-dependent tools are included only when the relay can actually perform them: advertising `post` on a relay with no way to speak out of band would be a tool that exists solely to fail.