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
- func NewFileClient(botToken string) *http.Client
- type Config
- type Handler
- func (h *Handler) BranchTasks(ctx context.Context, sessionKey string, tasks []slackmcp.BranchTask) ([]slackmcp.BranchResult, error)
- func (h *Handler) CatchUp(ctx context.Context, evs []slackproto.Event)
- func (h *Handler) Handle(ctx context.Context, ev slackproto.Event)
- func (h *Handler) HandleReaction(ctx context.Context, r slackproto.Reaction)
- func (h *Handler) Origin(sessionKey string) (slackmcp.Origin, bool)
- func (h *Handler) SetAPI(api *slack.Client)
- func (h *Handler) WaitIdle(ctx context.Context) error
Constants ¶
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 )
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.
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.
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
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 (*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
Origin resolves the thread sessionKey was branched out of, for the `history` tool's origin=true.