Documentation
¶
Overview ¶
Package team owns the wire protocol codebot uses on top of agentcore's team primitives. agentcore/team supplies the mailbox/registry/runner mechanism; this package supplies the format and policy choices:
- <teammate-message teammate_id=... color=... summary=...> XML envelopes for everything the model sees;
- idle_notification JSON envelopes carrying the teammate's last assistant text across agent boundaries;
- shutdown_request JSON envelopes for graceful teammate exit;
- the priority order (shutdown > leader > peer, FIFO within tier).
Keeping these out of agentcore means a future project can plug a different envelope format (e.g. plain JSON, OpenAI tool-call shape) into the same runner without forking agentcore.
Index ¶
- Constants
- func EncodeIdleNotification(from, text string) string
- func EncodeShutdownRequest(reason string) string
- func FallbackIdleStatus(from string) string
- func FormatTaskClaimPrompt(taskID, subject, description string) string
- func FormatTeammateAttachment(from, text, color, summary string) string
- func Hooks(opts HookOptions) coreteam.ProtocolHooks
- func IdleNotificationText(text string) string
- func IsIdleNotification(text string) bool
- func IsShutdownRequest(text string) bool
- func ParseTeammateAttachment(s string) (from, body string, ok bool)
- func PickPriority(queue []coreteam.Message) int
- type HookOptions
Constants ¶
const DefaultTeamName = "default"
DefaultTeamName is the placeholder name bootstrap assigns to the team pre-created at session startup. Tools that surface team state to the model (team_create's result message in particular) use it to recognise the "still on the default name" case and word their response accordingly.
Variables ¶
This section is empty.
Functions ¶
func EncodeIdleNotification ¶
EncodeIdleNotification produces the JSON envelope the leader-side pump inspects to surface a teammate's turn output. `text` is the teammate's last assistant message — empty for tool-only turns, in which case the pump injects a short status line instead.
func EncodeShutdownRequest ¶
EncodeShutdownRequest produces the JSON envelope that triggers a teammate's graceful exit. The teammate runner picks this up at the next turn boundary (top priority, see PickPriority) and returns from Run without consulting the model. `reason` is for transcript/UI only.
func FallbackIdleStatus ¶
FallbackIdleStatus is the human-readable line the leader sees when a teammate ends a turn with no assistant text (tool-only turn). The pump uses it as a fall-through after IdleNotificationText returns "".
func FormatTaskClaimPrompt ¶
FormatTaskClaimPrompt is the text fed straight to a teammate's next turn when IdleClaim pulls a task. The "Complete all open tasks" preamble keeps the model focused on the wider list rather than treating the claimed item as its only assignment.
func FormatTeammateAttachment ¶
FormatTeammateAttachment wraps text into the XML envelope the model expects. `from` is required; `color` and `summary` are optional and omitted when blank.
func Hooks ¶
func Hooks(opts HookOptions) coreteam.ProtocolHooks
Hooks returns the agentcore protocol-hook bundle wired with codebot's envelope format and priority policy. The synthetic initial prompt and every later inbound message both flow through FormatPrompt.
func IdleNotificationText ¶
IdleNotificationText extracts the assistant text from an idle envelope. Returns "" when text is not an idle envelope or carries no text.
func IsIdleNotification ¶
IsIdleNotification reports whether text is the idle-wake envelope. Exported so the leader-side pump can filter these before injecting into the prompt stream (when no text is present it surfaces a status line instead of the envelope itself).
func IsShutdownRequest ¶
IsShutdownRequest reports whether text is a shutdown_request envelope.
func ParseTeammateAttachment ¶
ParseTeammateAttachment is the inverse of FormatTeammateAttachment. Returns (from, body, true) on a valid envelope, ("", "", false) on anything that doesn't match — broken envelopes fall through to plain rendering at callers.
Tolerant of attribute ordering, missing optional attributes, and surrounding whitespace; strict about needing a non-empty teammate_id and a matching closing tag.
func PickPriority ¶
PickPriority chooses the highest-priority message index from queue. Tier order: shutdown_request (0) > team-lead (1) > peer (2). Within a tier, lowest index wins, preserving FIFO arrival.
Scanning shutdown across the whole queue first prevents a peer-DM flood from starving shutdown handling.
Types ¶
type HookOptions ¶
type HookOptions struct {
// IdleClaim, when set, lets the runner pull a synthetic prompt from
// the application instead of (or alongside) waiting on the mailbox.
// ctx carries the teammate identity via coreteam.WithIdentity so
// implementations can decide who is allowed to claim what.
IdleClaim func(ctx context.Context) (synthPrompt string, ok bool)
// IdleClaimInterval is the period at which the runner re-tries
// IdleClaim while parked on the mailbox. Zero means "only try once
// per turn boundary, then block until a real message arrives" —
// non-zero is needed when tasks can appear without any mailbox
// traffic (e.g. leader creates todos without send_message).
IdleClaimInterval time.Duration
}
HookOptions wires application-supplied callbacks into the protocol hook bundle. Today the only opt-in is IdleClaim (work-stealing); other fields are universal policy. Wrapping in a struct lets future opt-ins join without another signature break.
Source Files