relaytool

package
v0.26.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 28, 2026 License: MIT Imports: 8 Imported by: 2

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

View Source
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

type Tool struct {
	Name        string
	Description string
	Schema      map[string]any
	Handler     mcphost.Handler
}

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 New

func New(cfg Config) (*Tools, error)

New constructs a Tools.

func (*Tools) EndTurn

func (t *Tools) EndTurn(convToken string)

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) Register

func (t *Tools) Register(h *mcphost.Host)

Register installs the tool set on h, in Tools order.

func (*Tools) Tools

func (t *Tools) Tools() []Tool

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL