renderrefs

Documentation

Overview

Package renderrefs defines the sideband protocol that lets agent CLI commands announce a freshly created (or referenced) Stella entity — a task, goal, or recally article — so the chat UI can render a rich card instead of a raw UUID.

The producer (a CLI command, gated by Enabled) writes one sentinel line per reference to its stderr via Emit. The consumer (the tool-result ingest path) runs Extract over the combined tool output to lift the references out and strip the sentinel lines, so the text shown to the model and the user stays clean. References are derived data: nothing is stored that a GET on the entity could not re-derive, so there is no migration and stale previews never lie — the frontend always hydrates by id.

Index

• func Emit(w io.Writer, ref Reference) error
• func Enabled() bool
• type Preview
• type Reference
  • func Extract(text string) (clean string, refs []Reference)

Functions

func Emit

func Emit(w io.Writer, ref Reference) error

Emit writes one sentinel line for ref to w (typically a command's stderr). It is a no-op (returning nil) unless emission is Enabled, so a human running the same CLI in a terminal never sees the marker — only agent runs, where the bash tool sets the env, do. It is also a no-op when ref carries no id/type, so callers can emit unconditionally without guarding on partial data.

func Enabled

func Enabled() bool

Enabled reports whether the current process should emit sentinels.

Types

type Preview

type Preview struct {
	Title  string `json:"title,omitempty"`
	Status string `json:"status,omitempty"`
}

Preview is a best-effort snapshot used only as a loading placeholder. It is never trusted: the frontend hydrates the live entity by id, so a forged or stale preview cannot grant access or misrepresent state past first paint.

type Reference

type Reference struct {
	V       int      `json:"v"`
	Type    string   `json:"type"`               // "task" | "goal" | "recally_article" | future
	ID      string   `json:"id"`                 // entity UUID
	Intent  string   `json:"intent,omitempty"`   // "created" (default emitted) | "referenced"
	AgentID string   `json:"agent_id,omitempty"` // owning agent, for deep links to agent-scoped pages (task/goal)
	Preview *Preview `json:"preview,omitempty"`
}

Reference is one renderable entity reference. Type and ID are the only load- bearing fields; everything else is a hint.

func Extract

func Extract(text string) (clean string, refs []Reference)

Extract pulls every sentinel reference out of text and returns the text with those lines removed. Lines are matched anchored at their start (after leading whitespace), so a sentinel survives stdout/stderr interleaving and tail truncation as long as the line itself is intact. Malformed sentinel lines are dropped silently rather than surfaced as garbage to the user.