statusline

package
v0.52.2 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 2 Imported by: 0

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

View Source
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.

View Source
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.

View Source
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

func CapRunes(s string, n int) string

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

func ParseMeta(meta map[string]any) (mood, plan string, ok bool)

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

func ProviderEmoji(slug string) string

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

func ProviderEmojiForModel(modelID string) string

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

func Segments(s Status) []string

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

func ShortModelName(modelID string) string

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 '/'):

  1. drop the "<provider>/" prefix
  2. drop a trailing date stamp "-YYYYMMDD" and a trailing "-latest" / "-preview" (repeatedly, so "-preview-20251101" fully unwinds)
  3. drop a leading vendor echo already carried by the emoji ("claude-", "anthropic-"); keep meaningful family prefixes
  4. turn version dashes BETWEEN DIGITS into dots ("4-5" → "4.5"), leaving name dashes ("gpt-5-codex") alone
  5. 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).

Jump to

Keyboard shortcuts

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