GeezerVison

func AdapterAs[T any](c *Chat, adapterName string) (T, bool)

type Actor struct {
	Adapter string
	Tenant  string
	ID      string
	Name    string
	BotKind BotKind
}

type Adapter interface {
	Name() string
	Init(context.Context) error
	Shutdown(context.Context) error
	Webhook(DispatchFunc) http.Handler
	ValidateThreadID(ThreadID) (ThreadRef, error)
	PostMessage(context.Context, ThreadRef, PostableMessage) (*SentMessage, error)
	BotActor() Actor
}

type Attr struct {
	Key   string
	Value string
}

func AdapterAttr ¶

func AdapterAttr(adapter string) Attr

AdapterAttr tags an observation with the originating adapter name.

func OutcomeAttr ¶

func OutcomeAttr(outcome DispatchOutcome) Attr

OutcomeAttr tags an observation with a terminal DispatchOutcome.

func ReasonAttr ¶

func ReasonAttr(reason string) Attr

ReasonAttr tags an ignored-event observation with why it was ignored.

func RouteAttr ¶

func RouteAttr(route string) Attr

RouteAttr tags an observation with the routing decision (new-mention, subscribed-message, command, interaction).

func TenantAttr ¶

func TenantAttr(tenant string) Attr

TenantAttr tags an observation with the Platform Tenant.

type BotKind int

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

func New ¶

func New(ctx context.Context, opts ...Option) (*Chat, error)

func (*Chat) OnCommand ¶

func (c *Chat) OnCommand(handler CommandHandler)

OnCommand installs or atomically replaces the single command handler. A Command Event routes here and never to the message hooks, even in a Subscribed Thread. This intentionally differs from Vercel Chat SDK's multiple-handler hooks.

func (*Chat) OnInteraction ¶

func (c *Chat) OnInteraction(handler InteractionHandler)

OnInteraction installs or atomically replaces the single interaction handler. An Interaction Event routes here and never to the message hooks. This intentionally differs from Vercel Chat SDK's multiple-handler hooks.

func (*Chat) OnNewMention ¶

func (c *Chat) OnNewMention(handler MessageHandler)

OnNewMention installs or atomically replaces the single new-mention handler. This intentionally differs from Vercel Chat SDK's multiple-handler hooks.

func (*Chat) OnSubscribedMessage ¶

func (c *Chat) OnSubscribedMessage(handler MessageHandler)

OnSubscribedMessage installs or atomically replaces the single subscribed-message handler. This intentionally differs from Vercel Chat SDK's multiple-handler hooks.

func (*Chat) Shutdown ¶

func (c *Chat) Shutdown(ctx context.Context) error

func (*Chat) Thread ¶

func (c *Chat) Thread(ctx context.Context, id ThreadID) (*Thread, error)

func (*Chat) Webhook ¶

func (c *Chat) Webhook(adapterName string) (http.Handler, error)

type Command struct {
	Name  string
	Text  string
	Args  []string // advisory whitespace split of Text, not a parser
	Actor Actor
	Raw   any // Platform Escape Hatch: response_url, trigger_id, Teams invoke value
}

type CommandEvent struct {
	Event   *Event
	Thread  *Thread
	Command *Command
}

type CommandHandler func(context.Context, *CommandEvent) error

type ConcurrencyStrategy int

type DispatchFunc func(context.Context, *Event) error

type DispatchMode int

type DispatchOutcome string

type DispatchSpan interface {
	End(outcome DispatchOutcome, attrs ...Attr)
}

type EphemeralOptions struct {
	FallbackToDM bool
}

type EphemeralPoster interface {
	PostEphemeralMessage(context.Context, ThreadRef, Actor, PostableMessage, EphemeralOptions) (*SentMessage, error)
}

type Event struct {
	ID            string
	Adapter       string
	Tenant        string
	ThreadID      ThreadID
	DirectMessage bool
	// At most one of Message, Command, or Interaction is set: a Command Event and
	// an Interaction Event are Events, never Messages.
	Message     *Message
	Command     *Command
	Interaction *Interaction
	Retry       RetryMetadata
	Raw         any
}

type HistoryQuery struct {
	// Limit is the desired page size. The adapter clamps it to the platform's
	// maximum and applies its own default when Limit <= 0.
	Limit int
	// Before is an optional opaque cursor: a Message.ID returned by a prior page.
	// It is a plain string (NOT a fabricated MessageID type); the adapter
	// interprets it per its platform read API.
	Before string
}

type HistoryReader interface {
	ReadHistory(context.Context, ThreadID, HistoryQuery) ([]Message, error)
}

type Install struct {
	// Tenant is the Platform Tenant this record authorizes.
	Tenant string
	// Credential is an adapter-specific payload reached as a Platform Escape Hatch
	// for credentials (e.g. slack.SlackInstall, linear.LinearInstall). It is not a
	// normalized token model; each adapter documents and decodes the concrete type
	// it requires.
	Credential any
	// BotActorID is an optional pre-discovered bot identity used for tenant-correct
	// self-filtering. When empty the adapter falls back to any identity carried in
	// the adapter-specific Credential.
	BotActorID string
}

type InstallStore interface {
	// Lookup returns the install record for one Platform Tenant under the named
	// adapter. The adapter parameter lets one application store serve multiple
	// adapters keyed by name. ErrInstallNotFound means the tenant is not installed
	// and the adapter treats the webhook as an Ignored Event (acknowledge, do not
	// dispatch). Any other error is a transport failure the platform may retry.
	Lookup(ctx context.Context, adapter, tenant string) (Install, error)
}

type Interaction struct {
	Kind     InteractionKind
	ActionID string
	// Value is the activated component's single value: a button's value or the
	// selected option value of a single-select component (static_select,
	// external_select, overflow, radio_buttons). Empty when the component
	// carries no value.
	Value string
	// Values are the selected option values of a multi-valued component
	// (multi_static_select, checkboxes). Nil for single-valued components;
	// empty but non-nil when a multi-valued component's selection was cleared.
	Values []string
	Actor  Actor
	Raw    any // Platform Escape Hatch: response_url, trigger_id, view state
}

type InteractionEvent struct {
	Event       *Event
	Thread      *Thread
	Interaction *Interaction
}

type InteractionHandler func(context.Context, *InteractionEvent) error

type InteractionKind int

type LockLease struct {
	Key   string
	Token string
}

type LockScope int

type Message struct {
	ID        string
	Text      string
	Author    Actor
	Mentioned bool
	Raw       any
}

type MessageEvent struct {
	Event   *Event
	Thread  *Thread
	Message *Message
}

type MessageFormat int

type MessageHandler func(context.Context, *MessageEvent) error

type NativeContent struct {
	// Adapter must match the target adapter; a mismatch is an error, never a
	// silent portable downgrade.
	Adapter string
	Payload any
}

type NativeContentPoster interface {
	PostNative(context.Context, ThreadRef, NativeContent) (*SentMessage, error)
}

type ObservationName string

type Observer interface {
	// Event records a discrete, counter-style observation with low-cardinality
	// attributes.
	Event(ctx context.Context, name ObservationName, attrs ...Attr)
	// Dispatch opens a span for one Runtime Dispatch and returns a DispatchSpan
	// whose End records the terminal outcome and latency. Under deferred dispatch
	// the span follows the Detached Work Context so Ack-Then-Work latency is
	// measured to handler completion.
	Dispatch(ctx context.Context, attrs ...Attr) (context.Context, DispatchSpan)
}

type Option func(*config)

func WithAdapter ¶

func WithAdapter(adapter Adapter) Option

func WithLogger ¶

func WithLogger(logger *slog.Logger) Option

func WithObserver ¶

func WithObserver(observer Observer) Option

WithObserver installs an Observer. The default is an internal no-op observer, so an unconfigured runtime behaves exactly as today: structured slog only, with no third-party metrics dependency.

func WithRuntimeOptions ¶

func WithRuntimeOptions(options RuntimeOptions) Option

func WithState ¶

func WithState(state State) Option

type PostableMessage struct {
	Text   string
	Format MessageFormat
}

func Markdown ¶

func Markdown(text string) PostableMessage

func Text ¶

func Text(text string) PostableMessage

type RetryMetadata struct {
	Num    string
	Reason string
}

type RuntimeOptions struct {
	DedupeTTL     time.Duration
	ThreadLockTTL time.Duration
	Concurrency   ConcurrencyStrategy
	Dispatch      DispatchMode
	DetachTimeout time.Duration
	// LockScope selects the Thread Lock key: per Thread (default) or per
	// channel.
	LockScope LockScope
	// DebounceInterval is the ConcurrencyDebounce quiet period. It must be
	// positive under that strategy and is ignored otherwise.
	DebounceInterval time.Duration
	// MaxConcurrent bounds simultaneous handler executions under
	// ConcurrencyConcurrent. It must be positive under that strategy and is
	// ignored otherwise.
	MaxConcurrent int
	// BurstWindow is the ConcurrencyBurst collection window: routed events for
	// a scope collect for this long — anchored at the window's first member,
	// never extended by later arrivals — before dispatching as one batch. It
	// must be positive under that strategy and is ignored otherwise. The
	// window is collection time, not execution time: it does not consume the
	// batch's lock-wait budget or any member's DetachTimeout.
	BurstWindow time.Duration
	// MaxBurstBatch caps how many members one burst batch may collect. A
	// window reaching the cap seals immediately, with the cap-reaching member
	// as the sealed batch's last member; the next event opens a rolled window
	// dispatched strictly after its predecessor. The cap shapes batches — it
	// never rejects or drops an accepted member (delivery-preserving shaping,
	// ADR 0015) — and parked members remain bounded by MaxDetached regardless.
	// Zero disables the cap; it must not be negative under the burst strategy
	// and is ignored otherwise.
	MaxBurstBatch int
	// MaxDetached is the deferred-dispatch Admission Bound (ADR 0015): a
	// per-instance cap on admitted-but-incomplete deferred deliveries.
	// Everything a delivery retains under DispatchDeferred counts against it —
	// running detached tails, parked queue/debounce waiters, concurrent
	// slot-waiters, and parked burst batch members — and capacity frees only
	// when that retention ends. A delivery arriving at the cap is rejected
	// with ErrAdmissionRejected
	// before acknowledgement and before dedupe marking, so a platform retry is
	// never deduped away. It must be positive under DispatchDeferred and is
	// ignored under DispatchSync; DefaultRuntimeOptions sets 1024.
	//
	// Sizing: the bound is a count, not bytes — the runtime cannot measure
	// retained platform payloads or handler closures. Budget roughly
	// MaxDetached x (platform payload ceiling + one goroutine stack + whatever
	// the handler closure pins) against the instance's memory; sustained
	// rejection is the platform-visible backpressure signal, so size the cap
	// to be reached only under genuine overload and keep front-door rate
	// limiting for fleet-level control.
	MaxDetached int
	// MaxDetachedPerTenant additionally caps any single installation's share
	// of MaxDetached, keyed on the delivery's (adapter, tenant) installation
	// identity (ADR 0006). It is a ceiling through the same rejection path,
	// not a reservation: a hot tenant is capped, but no capacity is guaranteed
	// to the others. Zero disables the ceiling; it must not be negative under
	// DispatchDeferred and is ignored under DispatchSync.
	MaxDetachedPerTenant int
}

func DefaultRuntimeOptions ¶

func DefaultRuntimeOptions() RuntimeOptions

type SentMessage struct {
	ID       string
	ThreadID ThreadID
	Raw      any
}

type State interface {
	IsThreadSubscribed(context.Context, ThreadID) (bool, error)
	SubscribeThread(context.Context, ThreadID) error
	UnsubscribeThread(context.Context, ThreadID) error
	MarkEvent(context.Context, string, time.Duration) (bool, error)
	AcquireLock(context.Context, string, time.Duration) (LockLease, bool, error)
	ExtendLock(context.Context, LockLease, time.Duration) (bool, error)
	ReleaseLock(context.Context, LockLease) (bool, error)
	Shutdown(context.Context) error
}

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

func (*Thread) ID ¶

func (t *Thread) ID() ThreadID

func (*Thread) Post ¶

func (t *Thread) Post(ctx context.Context, msg PostableMessage) (*SentMessage, error)

func (*Thread) PostEphemeral ¶

func (t *Thread) PostEphemeral(ctx context.Context, actor Actor, msg PostableMessage, opts EphemeralOptions) (*SentMessage, error)

func (*Thread) Subscribe ¶

func (t *Thread) Subscribe(ctx context.Context) error

func (*Thread) Unsubscribe ¶

func (t *Thread) Unsubscribe(ctx context.Context) error

type ThreadID string

type ThreadRef struct {
	ID      ThreadID
	Adapter string
	Tenant  string
	Channel string
	Root    string
	Direct  bool
	Raw     any
}