Documentation
¶
Overview ¶
Package statusline defines the wire contract for the dev.acp-kit.status-line/v1 ACP extension: a tiny mood/plan status line that agents emit on session/update._meta so chat relays (poe-acp, slack-acp, …) can render a compact identity + progress line alongside the assistant's reply.
Scope: only the shared, relay-agnostic pieces live here — the extension id, length cap, Status type, provider→emoji map, model short-name derivation, and ParseMeta. Each relay keeps its own renderer because the markup (poe markdown vs. Slack mrkdwn), the surface (animated spinner vs. static placeholder) and the placement (poe-acp renders it as an italic footer under the answer) differ.
Wire shape:
_meta: {
"dev.acp-kit.status-line/v1": {
"mood": "<short label, ≤12 runes>",
"plan": "<short label, ≤12 runes>"
}
}
Both fields are opaque short strings; agents stay polite within ~12 runes per field, ParseMeta enforces the cap on the consumer side. The payload can ride along on any session/update kind (agent_message_chunk, agent_thought_chunk, tool_call, …) — relays read _meta irrespective of update kind.
Index ¶
Constants ¶
const ExtensionID = "dev.acp-kit.status-line/v1"
ExtensionID is the _meta key both sides use to advertise support and to carry per-update mood/plan payloads.
const MaxFieldRunes = 12
MaxFieldRunes caps the rendered length of mood and plan. Mobile chat surfaces have very little horizontal room; an oversize agent label must not push the header off-screen or wrap.
const MaxTrailingFieldRunes = 36
MaxTrailingFieldRunes caps the LAST segment of a status line — the live activity label (the running tool / progress verb a relay appends after mood and plan). It is deliberately wider than MaxFieldRunes: the trailing segment has nothing after it, so an oversize value can only spill at the very end of the line instead of pushing the mood/plan header off a narrow screen, and a real progress string ("wait poll 7: step 1/1 Bash") is meaningless when clipped to twelve runes.
Only the trailing segment may use this cap — earlier fields stay at MaxFieldRunes so the header itself keeps its mobile-safe width.
Variables ¶
This section is empty.
Functions ¶
func CapRunes ¶
CapRunes truncates s to at most n runes. No ellipsis is appended: the cap is tight (12 runes) and the agent picks the label, so an ellipsis would only steal another character of meaning. Returns "" when n <= 0.
func ParseMeta ¶
ParseMeta extracts the v1 mood/plan fields from a session/update _meta map. Returns (mood, plan, ok). ok is true if the extension key was present, regardless of whether mood/plan themselves were set. Both fields are returned trimmed and capped to MaxFieldRunes.
Unknown sub-keys are ignored; non-string values are treated as absent rather than rejected (forward compat).
The ACP SDK decodes _meta as map[string]any with sub-objects landing as either map[string]any or json.RawMessage depending on call path; both are handled here.
func ProviderEmoji ¶
ProviderEmoji maps a provider slug (case-insensitive) to the emoji shown in the status header. Returns "" for unknown providers, which callers treat as a dropped segment.
The mapping is relay-owned by design — the relay knows which provider is currently servicing the turn — but it's kept here so every relay renders the same agent with the same emoji. Add new providers as they appear in fir's models registry.
func ProviderEmojiForModel ¶
ProviderEmojiForModel resolves the provider emoji from a fully qualified model id of the form "<provider>/<model>" (the convention fir uses for its SessionModelState.currentModelId). An id with no '/' or an empty id returns "" — caller treats that as "drop the segment".
func Segments ¶
Segments returns the non-empty header segments in order: the model identity (provider emoji + short model name), mood, plan. Empty entries are dropped so a missing mood doesn't leave a stray separator. Relays use this as the building block for their own Header/Spinner renderers, joining with their preferred separator and wrapping in surface-specific markup.
Emoji and model name form a SINGLE segment joined by one space ("🏛️ opus-4.5"): they name one thing, and a bullet between them would read as two independent fields. Either half alone degrades to just that half.
func ShortModelName ¶ added in v0.10.0
ShortModelName derives the compact model label shown next to the provider emoji from a fully qualified model id ("<provider>/<model>", the convention fir uses). It is a display helper, not an identifier: the result is lossy by design and must never be fed back onto the wire.
Rules, applied in order to the part after "<provider>/" (the whole string when there is no '/'):
- drop the "<provider>/" prefix
- drop a trailing date stamp "-YYYYMMDD" and a trailing "-latest" / "-preview" (repeatedly, so "-preview-20251101" fully unwinds)
- drop a leading vendor echo already carried by the emoji ("claude-", "anthropic-"); keep meaningful family prefixes
- turn version dashes BETWEEN DIGITS into dots ("4-5" → "4.5"), leaving name dashes ("gpt-5-codex") alone
- lowercase and cap to MaxFieldRunes
An empty id returns "" — callers treat that as "drop the segment".
Types ¶
type Status ¶
type Status struct {
// ProviderEmoji is the relay-resolved emoji for the model
// servicing the turn. Empty means unknown provider or the relay
// has no per-turn model concept — segment is then dropped.
ProviderEmoji string
// Model is the short, human-readable name of the model servicing
// the turn ("opus-4.5", "gpt-5-codex"), normally derived from the
// fully qualified model id with ShortModelName. It renders in the
// SAME segment as ProviderEmoji, separated by a single space —
// emoji and model name are one unit ("🏛️ opus-4.5"), not two
// bullet-separated fields. Empty means unknown.
Model string
// Mood is the agent-supplied mood label (opaque string).
Mood string
// Plan is the agent-supplied plan progress label (opaque string).
Plan string
}
Status is the renderable state of one status header. Relays build this from ParseMeta (mood/plan) and their own provider-resolution logic (provider emoji).