summarize

Documentation

Overview

Package summarize produces one-line summaries of agent sessions: a live "what it's doing now" activity line (Line 2 of the session card) and a durable session title (Line 1). Both share one backend selected at startup from config — either the on-device Apple Foundation Model (macOS, free) or a hosted/local agent CLI invoked in print mode (claude/pi/codex; works on Linux). The daemon is the only caller.

The seam is the Summarizer interface: kind-selectable prompts keep the two use-cases on one backend, while FromConfig picks the concrete impl from host capability + user consent. A circuit breaker wraps every impl so a flaky backend disables itself instead of starving the panel.

Index

• Constants
• func ActivityInstruction() string
• func TitleAttemptInstruction() string
• func TitleForceInstruction() string
• type Noop
  • func (Noop) Backend() string
  • func (Noop) Summarize(_ context.Context, _, _ string) (string, error)
• type Probes
• type Result
  • func FromConfig(cfg config.SummarizerConfig, caps config.HostCaps, probes Probes) Result
• type Summarizer

Constants

const HelperEnvTag = "RMOTE_SUMMARIZER_HELPER=1"

HelperEnvTag is set on every helper subprocess so the daemon's hook ingest can recognize helper-origin processes and suppress them — preventing the recursion loop (helper → hook → summarize → helper …) flagged in advisory (b). The server's hook/session-creation path checks this env.

Functions

func ActivityInstruction

func ActivityInstruction() string

ActivityInstruction builds the Line-2 live-task prompt: terse present-tense activity, ≤12 words.

func TitleAttemptInstruction

func TitleAttemptInstruction() string

TitleAttemptInstruction builds the self-gated Line-1 title prompt: the model returns a ≤6-word title if it can determine one, else exactly "UNCLEAR". Drives the dynamic-N lifecycle (a clear session names itself on turn 1; a vague one returns UNCLEAR until enough prompts accumulate).

func TitleForceInstruction

func TitleForceInstruction() string

TitleForceInstruction builds the best-effort title prompt, used after maxAttempts UNCLEARs: name the task from whatever is inferable (no UNCLEAR option). Guarantees every session graduates off the placeholder.

Types

type Noop

type Noop struct{}

Noop implements Summarizer by returning "". Used when the resolved backend is Disabled or consent is missing — keeps the call sites uniform.

func (Noop) Backend

func (Noop) Backend() string

func (Noop) Summarize

func (Noop) Summarize(_ context.Context, _, _ string) (string, error)

type Probes

type Probes interface {
	AppleFMPath() string               // "" if the rmoted-summarize helper is absent
	AgentBinary(agentID string) string // "" if that agent CLI isn't on PATH
}

Probes abstract host capability lookups so this package doesn't import the agents catalog or resolve the applefm path itself (avoids cycles + keeps the package unit-testable with fakes).

type Result

type Result struct {
	S        Summarizer
	Backend  string // resolved backend id (config.Backend*)
	Agent    string // resolved agent id for agentcli, else ""
	Reason   string // human-readable selection rationale
	Degraded bool   // true if a usable backend couldn't be established
}

Result bundles the constructed summarizer with what was actually chosen, so the server can log the decision and surface consent/degraded state.

func FromConfig

func FromConfig(cfg config.SummarizerConfig, caps config.HostCaps, probes Probes) Result

FromConfig resolves the backend + agent from cfg + host capability, enforces off-device consent, and returns a wired Summarizer (applefm, agentcli, or Noop). Never returns a nil interface. callerSupplied probes (appleFmPath, agentBinaries) keep this package free of an agents/config import cycle at probe time — the server, which owns those, passes them in.

type Summarizer

type Summarizer interface {
	Summarize(ctx context.Context, instruction, text string) (string, error)
	// Backend returns the resolved backend id (config.BackendAppleFM / AgentCLI
	// / Disabled) so the server can log + surface what is active.
	Backend() string
}

Summarizer reduces a blob of cleaned text to one short line under a caller-supplied instruction (system prompt). The daemon owns ALL prompt logic — activity line, self-gated title, best-effort title, SAME/NEW topic classification — via the Instruction* builders below, so the applefm and agentcli backends behave identically. Implementations must be safe for concurrent use and respect ctx. An empty result is valid (caller keeps last).