channel

Documentation

Overview

Package channel defines the connector seam. Connectors self-register via Register (one package + one init line each) and decode their own raw JSON config section, so adding WhatsApp/Twilio/Slack/... never touches core.

Index

• Variables
• func BindTurns(ch Channel, wait, steer TurnFunc)
• func Register(name string, f Factory)
• func Registered() []string
• func SplitMessage(content string, limit int) []string
• func Validate(cfgs map[string]json.RawMessage) error
• type Addresser
• type Channel
  • func Build(cfgs map[string]json.RawMessage, b *bus.MessageBus) []Channel
• type Factory
• type Guarded
• type Manager
  • func NewManager(b *bus.MessageBus, channels []Channel) *Manager
  • func (m *Manager) Interim(sessionKey, content string)
  • func (m *Manager) Names() []string
  • func (m *Manager) Serves(name string) bool
  • func (m *Manager) SetTyping(sessionKey string, on bool)
  • func (m *Manager) Start(ctx context.Context)
  • func (m *Manager) Stop()
• type Steerable
• type Toolset
• type TurnFunc
• type TurnRunner
• type Typer

Variables

var ErrUnknownChannel = fmt.Errorf("unknown outbound channel")

ErrUnknownChannel reports an outbound message for a channel the manager does not own.

Functions

func BindTurns

func BindTurns(ch Channel, wait, steer TurnFunc)

BindTurns wires a connector's turn runner to the entry point its replies can come back through: steer where Steerable says the bus can deliver them, wait where they have to be returned here. A connector that does not run its own turns is left alone.

func Register

func Register(name string, f Factory)

Register installs a connector factory (call from the connector's init).

func Registered

func Registered() []string

Registered lists known connector names.

func SplitMessage

func SplitMessage(content string, limit int) []string

SplitMessage chunks content at a channel's length limit, preferring newline then space boundaries.

func Validate

func Validate(cfgs map[string]json.RawMessage) error

Validate builds every enabled, known section against a throwaway bus and reports the first one its connector rejects. It is what the gateway checks before reloading itself over a config edit: Build skips a broken section with a log line, which under a live reload would silently drop a channel the user only mistyped. Nothing is started; the constructions are discarded.

Types

type Addresser

type Addresser interface {
	BindLastExternal(func() (channel, chatID string, ok bool))
}

Addresser is the optional capability of a connector that sometimes has to hand a message to the user's usual written conversation — a spoken exchange asked to answer in writing. The host binds where that is: the gateway hands it the loop's last external chat, the CLI its own terminal session. Bound before Start.

type Channel

type Channel interface {
	Name() string
	Start(ctx context.Context) error
	Stop() error
	Send(ctx context.Context, msg bus.OutboundMessage) error
	MaxMessageLength() int // 0 = unlimited
}

Channel is one chat connector. Start must be non-blocking (spawn your own goroutines off ctx); Send delivers one already-chunked message.

func Build

func Build(cfgs map[string]json.RawMessage, b *bus.MessageBus) []Channel

Build instantiates every enabled configured channel. Unknown or disabled sections are skipped with a log line, never an error, so configs stay forward-compatible.

type Factory

type Factory func(raw json.RawMessage, b *bus.MessageBus) (Channel, error)

Factory builds a channel from its raw config section.

type Guarded

type Guarded interface {
	BindPathGuard(*tools.PathGuard)
}

Guarded is the optional capability of a connector that reads or writes files itself — sending a chat a local file, saving one it received — and so must obey the same path rules as every file tool. Bound before Start.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager starts channels and pumps the outbound bus to them with chunking and bounded retry.

func NewManager

func NewManager(b *bus.MessageBus, channels []Channel) *Manager

func (*Manager) Interim

func (m *Manager) Interim(sessionKey, content string)

Interim delivers a note from a turn that is still running to the chat it belongs to, so a long turn reads as work in progress rather than silence. It goes through the outbound bus like any reply, keeping it in order with the answer that follows. Sessions of channels this manager does not own (cli, cron, jobs) are ignored.

func (*Manager) Names

func (m *Manager) Names() []string

func (*Manager) Serves

func (m *Manager) Serves(name string) bool

Serves reports whether a connector is running for this channel — whether a message addressed to it can actually reach the user.

func (*Manager) SetTyping

func (m *Manager) SetTyping(sessionKey string, on bool)

SetTyping routes a session's busy state to the channel it belongs to, for connectors that can show one. Session keys of channels this manager does not own (cli, cron, heartbeat) are ignored.

func (*Manager) Start

func (m *Manager) Start(ctx context.Context)

Start launches every channel and the outbound pump.

func (*Manager) Stop

func (m *Manager) Stop()

Stop stops all channels and waits for the pump to drain.

type Steerable

type Steerable interface {
	AcceptsSteering()
}

Steerable is the optional capability of a TurnRunner whose replies also reach the user through Send. It says a turn this connector starts may be folded into one already live for the same session — a background job reporting back, a cron result — instead of queuing behind it: the words land while they are still what the conversation is about, and the running turn's reply comes back the usual way. Without it a connector's turn waits for the session, which is what a phone call needs, since a reply published to the bus would be dialled as a second call rather than spoken on the line the caller is holding.

type Toolset

type Toolset interface {
	Toolset() []tools.Tool
}

Toolset is the optional capability of contributing tools that only make sense where the connector is configured, so a machine without it never sees a tool that could only fail.

type TurnFunc

type TurnFunc func(ctx context.Context, content, sessionKey, speaker, audience string, notice func(string)) (string, error)

TurnFunc runs one synchronous turn and returns the reply (wired to Loop.ProcessDirectNotice). notice is called with each line the agent says on its way to that reply — "let me look that up" — as it says it, so a turn spent in tool calls is audible progress rather than a silence the user cannot tell from a hang. It runs on the turn's own goroutine, so a connector that takes time to deliver a note must not block in it. speaker names who is talking where the connector can tell (the microphone recognizing a household voice); blank means "whoever this chat is". audience says who can hear the reply — tools.AudienceShared where the connector knows somebody besides the user is present, blank everywhere else. It is separate from speaker because the two answer different questions: speaker decides attribution, audience decides discretion.

type TurnRunner

type TurnRunner interface {
	BindTurnRunner(run TurnFunc)
}

TurnRunner is the optional capability of a connector that runs turns itself instead of publishing them onto the bus. A phone call is synchronous — the caller is waiting on the line, and hanging up must cancel the turn — so the bus's fire-and-forget shape does not fit it.

type Typer

type Typer interface {
	SetTyping(chatID string, on bool)
}

Typer is the optional capability of showing the user that a turn is being worked on. Connectors whose protocol has no such signal simply omit it.