handler

package
v0.20.2 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Attachments in and out of a Slack thread.

Inbound: files a human shares with a message are downloaded (with the bot token, which needs files:read) into <session cwd>/inbox/<ts>/ and handed to the agent as ACP resource_link blocks plus a one-line note naming the local paths. Files persist with the thread's cwd, like the rest of its state. Every failure degrades to a note: a turn never fails because a download did.

Outbound: at the end of a turn every regular file the agent left in <session cwd>/outbox/ is uploaded into the thread (files:write) and moved to outbox/.sent/ so the next turn does not re-upload it.

This file is the branch feature: open a new Slack thread that continues this conversation.

A Slack conversation is a thread. A branch posts a NEW top-level message in the same channel — which opens a new thread — linking back to the branch point by permalink, and posts the new thread's link in the origin thread. The new thread's session is a fork of the origin's agent session (ACP session/fork) when the agent supports it, else a fresh one, and the child can read the origin up to the branch point with history(origin=true).

Three entry points share performBranch so they cannot drift: `!branch <text>`, a :fork_and_knife: reaction on a message, and the agent's `branch` MCP tool.

Package handler glues slackproto + router + acpclient: it turns inbound Slack events into ACP prompts and streams the agent's session updates back into a Slack thread message.

Index

Constants

View Source
const (
	// InboxDir receives inbound attachments, relative to the session cwd.
	InboxDir = "inbox"
	// OutboxDir is where the agent leaves files to upload.
	OutboxDir = "outbox"

	// DefaultMaxAttachmentBytes caps one inbound file.
	DefaultMaxAttachmentBytes int64 = 20 << 20
)
View Source
const DefaultCatchupTurns = 4

DefaultCatchupTurns is how many catch-up turns run at once. A long outage can leave many threads waiting, and starting all of their turns together would be a burst of agent prompts and Slack posts.

View Source
const MaxCatchupPerThread = 50

MaxCatchupPerThread bounds how many missed messages one thread's catch-up turn carries. The newest are kept: they are the ones a reader still waits on, and the header counts the rest.

View Source
const Platform = "slack"

Platform is the origin _meta platform this relay reports.

Variables

This section is empty.

Functions

func NewFileClient added in v0.16.0

func NewFileClient(botToken string) *http.Client

NewFileClient returns the HTTP client inbound downloads use: it authenticates as the bot. Redirects are not followed: the transport would re-attach the token to whatever host one points at.

Types

type Config

type Config struct {
	Router            *router.Router
	API               *slack.Client
	AllowedUserIDs    map[string]struct{}
	AllowedChannelIDs map[string]struct{}
	// OwnerUserIDs may run operator commands (!fir, !run, !skills,
	// !update, !login …). Empty: nobody may.
	OwnerUserIDs map[string]struct{}
	// NoProgressTimeout cuts a turn that has stopped making progress:
	// no agent output and no tool-call activity for this long. It is a
	// WEDGE guard, not a working bound — a legitimately long tool call
	// keeps resetting it, so a turn that is working is never cut.
	// Default 2m.
	NoProgressTimeout time.Duration
	// TurnCeiling is an OPT-IN absolute cap on one turn, enforced
	// regardless of progress. 0 (the default) means no ceiling: a turn
	// that keeps making progress runs as long as it needs.
	TurnCeiling time.Duration
	// Ambient enables forwarding of non-DM thread replies to threads
	// the bot is already part of. When false, only @-mentions and DMs
	// trigger responses.
	Ambient bool
	// Backfill enables catching up on missed messages via
	// conversations.replies when a gap is detected.
	Backfill bool
	// BackfillMaxMessages caps how many historical messages to fetch
	// when backfilling.
	BackfillMaxMessages int
	// SilentSentinel is the exact output string that signals the agent
	// has chosen not to reply.
	SilentSentinel string
	// HideThinking suppresses agent thought chunks from the Slack post
	// (the italic one-liners), mirroring poe-acp hide_thinking.
	HideThinking bool
	// SelfDrive is the escape-hatch state shared with slackproto. Nil
	// (the default) means the hatch is off and no self-drive event can
	// ever be admitted.
	SelfDrive *slackproto.SelfDrive
	// SelfDrivePerMinute caps how many hatch-accepted events the relay
	// will act on. 0 uses defaultSelfDrivePerMinute.
	SelfDrivePerMinute int
	// Now is the clock used by the self-drive rate cap. Injected by
	// tests; defaults to time.Now.
	Now func() time.Time
	// AgentPostsPerMinute caps the agent's `branch` tool tasks per
	// minute (each one posts a top-level message and starts a turn).
	// 0 uses defaultBranchesPerMinute.
	AgentPostsPerMinute int
	// FileClient downloads inbound attachments; it must authenticate as
	// the bot (see NewFileClient). Nil uses http.DefaultClient.
	FileClient *http.Client
	// MaxAttachmentBytes caps one inbound file. 0 uses
	// DefaultMaxAttachmentBytes.
	MaxAttachmentBytes int64
	// CatchupMaxAge: a missed message older than this is not answered
	// by the catch-up; its thread gets a one-line notice instead. 0
	// means no age bound.
	CatchupMaxAge time.Duration
	// CatchupTurns bounds how many catch-up turns run at once. 0 uses
	// DefaultCatchupTurns.
	CatchupTurns int
	// PerUserSessions is session_scope "thread_user": one agent session
	// per (thread, sender), replies @-mention the user they answer, and
	// a message supersedes only its sender's running turn.
	PerUserSessions bool
	// AgentCwd is cwd_mode "agent": the agent picks the cwd, and the
	// login commands are each sender's own rather than owner-only.
	AgentCwd bool
	// Interject opts into mid-turn quick replies (see interject.go).
	// The zero value is off.
	Interject interject.Config
}

Config configures the handler.

type Handler

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

Handler implements slackproto.Handler.

func New

func New(cfg Config) *Handler

New constructs a handler.

func (*Handler) BranchTasks added in v0.13.0

func (h *Handler) BranchTasks(ctx context.Context, sessionKey string, tasks []slackmcp.BranchTask) ([]slackmcp.BranchResult, error)

BranchTasks implements slackmcp.Brancher: the agent's `branch` tool.

func (*Handler) CatchUp added in v0.17.0

func (h *Handler) CatchUp(ctx context.Context, evs []slackproto.Event)

CatchUp turns one conversation's missed messages into turns. evs is oldest first, as the catch-up reads them.

Every event passes the same gates as a live one (admit). Then each thread's missed messages are COLLAPSED into one turn: a thread that had five messages while the relay was down gets one answer, not five turns that supersede each other. Relay commands are skipped — they were typed for a relay that was not there, and running `!new` or `!model` minutes later would surprise everybody. Messages older than CatchupMaxAge are not answered; each thread that had any gets a one-line notice instead.

The turns start off the caller's goroutine, at most CatchupTurns at a time, so live delivery is never held up behind them.

func (*Handler) Handle

func (h *Handler) Handle(ctx context.Context, ev slackproto.Event)

Handle is called by slackproto.Client for each inbound event.

func (*Handler) HandleReaction added in v0.13.0

func (h *Handler) HandleReaction(ctx context.Context, r slackproto.Reaction)

HandleReaction implements slackproto.ReactionHandler: a :fork_and_knife: on a message branches a new thread seeded with that message's text.

func (*Handler) Origin added in v0.13.0

func (h *Handler) Origin(sessionKey string) (slackmcp.Origin, bool)

Origin resolves the thread sessionKey was branched out of, for the `history` tool's origin=true.

func (*Handler) SetAPI

func (h *Handler) SetAPI(api *slack.Client)

SetAPI installs the Slack API client (used for posting/updating messages). Called by main after the slackproto.Client has been constructed.

func (*Handler) WaitIdle

func (h *Handler) WaitIdle(ctx context.Context) error

WaitIdle blocks until the handler has no in-flight prompts or ctx is done. Used by tests to synchronise on the inflight-empty transition without wall-clock polling; also useful for graceful shutdown paths.

Jump to

Keyboard shortcuts

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