protocol

type CounterEnricher ¶ added in v1.14.0

type CounterEnricher struct {
	// contains filtered or unexported fields
}

CounterEnricher is the V1 production Enricher. It aggregates the per-session counters from raw data owned by subsystems one package over — SUMMING, not reading a shadow store:

• total_cost_cents / total_tokens: summed from `llm.cost.recorded` events scoped to the session (via the event substrate).
• events_count: the count of the session's events from the durable event substrate (HistoryReplayer.ListWindow, bounded).
• tasks_count / has_failed_task: the session's tasks from the task registry.
• has_pending_intervention: a paused pause record from the pause registry scoped to the session.

Concurrent reuse (CLAUDE.md §5) ¶

A constructed *CounterEnricher is immutable after NewCounterEnricher: it holds only the bus / registry / coordinator references (each itself safe for concurrent reuse) plus a logger. Every Counters call's per-run state lives in its arguments and locals; the enricher reads nothing from itself for run-specific data.

func NewCounterEnricher(deps CounterEnricherDeps) (*CounterEnricher, error)

func (e *CounterEnricher) Counters(ctx context.Context, id identity.Identity, sessionID string) SessionCounters

type CounterEnricherDeps ¶ added in v1.14.0

type CounterEnricherDeps struct {
	// Bus is the event substrate the cost / tokens / events counters read
	// from. It MUST implement events.HistoryReplayer to serve the windowed
	// per-session scan; a bus without it yields honest-partial counters
	// (Partial=true, zero bus-derived counts), never a silent zero.
	Bus events.EventBus
	// Tasks is the task registry the tasks_count / has_failed_task counters
	// read from, scoped to the session.
	Tasks tasks.TaskRegistry
	// Pauses is the pause coordinator the has_pending_intervention counter
	// reads from, scoped to the session.
	Pauses pauseresume.Coordinator
	// Logger receives Warn-level diagnostics when a bounded scan truncates
	// or the substrate is unavailable (the degradation is NEVER silent —
	// it is both logged and surfaced as SessionCounters.Partial). Nil
	// routes to slog.Default().
	Logger *slog.Logger
}

CounterEnricherDeps carries the CounterEnricher's mandatory dependencies. All three are required — a nil dependency would silently drop a counter dimension (a value that reads zero on a busy session), the exact silent-absence class this phase closes, so NewCounterEnricher fails loud rather than build a half-blind enricher (CLAUDE.md §5).

type Enricher ¶ added in v1.14.0

type Enricher interface {
	// Counters returns the read-time counter rollup for one session,
	// aggregated from the cost-event stream, the task registry, the event
	// substrate, and the pause registry — all identity-scoped to `id` (the
	// session's own full triple). A zero-valued return is honest ("we don't
	// have this data"), never silent degradation. When the bounded
	// per-session scan hits its bound (or a retention gap), the returned
	// SessionCounters.Partial is set and the cost / tokens / events counts
	// are an HONEST LOWER BOUND, never a plausible exact number.
	Counters(ctx context.Context, id identity.Identity, sessionID string) SessionCounters
}

Enricher is the optional read-time counter-rollup backend the ListerProjector overlays onto a SessionRow. It mirrors the shipped tasks.Projector enricher SEAM — only the seam is inherited; the aggregation below is net-new (the tasks serve enricher returns a ZERO cost rollup, deferring cost to the event stream). Production wiring supplies a CounterEnricher backed by the event substrate + task registry + pause registry; tests and partial builds run without one.

A projector with no Enricher wired reports honest ZERO counters — "we don't have this data", not a silent degradation of a known value — and the Service loud-rejects a facet/sort over those counters (WARN-3, see protocol.go) so an unwired build can never reproduce the false-absence defect this phase closes.

type Eraser ¶ added in v1.7.0

type Eraser interface {
	// Erase performs the full erasure cascade for the verified identity
	// (own-session-only — the scope contract is enforced at the Service
	// edge before Erase is reached). Returns the deletion telemetry, or a
	// refusal: sessions.ErrSessionRunning (a RUNNING task) /
	// sessions.ErrSessionNotFound (absent under the caller's identity).
	Erase(ctx context.Context, id identity.Identity) (prototypes.SessionsDeleteResponse, error)
}

Eraser is the seam the Service depends on for `sessions.delete`. The V1 production implementation is the in-runtime cascade orchestrator (`sessions.CascadeEraser`), which performs the real three-store cascade + session-record delete for the verified identity, refusing fail-loud on a running task. The Service depends ONLY on this interface (CLAUDE.md §4.4) — a future remote / cross-runtime eraser slots in behind it without reshaping the Service.

type ListerProjector ¶

type ListerProjector struct {
	// contains filtered or unexported fields
}

ListerProjector is the V1 production Projector — a thin read-only projection over a `sessions.SessionLister` (the Registry's `ListSnapshots` surface). It maps the runtime `sessions.SessionSnapshot` onto the flat Protocol `SessionRow` wire shape (RFC §5.1 single-source rule: the Console never reads `sessions.Session`).

Identity scoping (CLAUDE.md §6) ¶

ListSessions builds the `sessions.SessionListFilter` so the registry scopes by tenant: a non-admin caller is restricted to its own `(tenant, user)`; an admin caller MAY widen via the request's `TenantIDs`. The registry's `ListSnapshots` does NOT re-check scope — the gate is the Service's `ErrCrossTenantScope` check; this projector only translates the gate decision into the filter shape.

Enrichment seam (CLAUDE.md §4.4) ¶

The SessionLister owns the lifecycle fields (status, timestamps, title, identity); it does NOT model the per-session cost / token / task / event counters or a session→agent binding. ListerProjector reads the counters through the optional Enricher seam (enricher.go), mirroring the shipped tasks.Projector enricher. When no Enricher is wired, the counters stay ZERO — honest ("we don't have this data"), not silent degradation — and the Service loud-rejects a facet/sort over them (WARN-3) so an unwired build never returns a false-empty counter page. Every row's explicit counter availability is marked via SessionRow.CounterStatus (current / partial / not_requested / unavailable) so a zero counter never reads as a measured zero.

Lifecycle-only projection ¶

`projection=lifecycle` requests (pageLifecycleOnly / inspectLifecycleOnly) are served from the catalog projection / page path BEFORE any Enricher call: the counters are never read, stay zero, and are marked CounterStatus=not_requested. The filter / sort / cursor / truncation and the identity-scope / admin-widening semantics are exactly the full projection's — only the counter payload is absent.

Concurrent reuse ¶

A constructed *ListerProjector is immutable after NewListerProjector and safe to share across N concurrent goroutines — it holds only the SessionLister + optional Enricher references (both themselves safe for concurrent reuse); every method's per-call state lives in the call's arguments and locals.

func NewListerProjector(lister sessions.SessionLister, opts ...ListerProjectorOption) (*ListerProjector, error)

func (p *ListerProjector) CountersAvailable() bool

func (p *ListerProjector) InspectSession(ctx context.Context, id identity.Identity, sessionID string, adminScoped bool) (prototypes.SessionsInspectResponse, error)

func (p *ListerProjector) ListSessions(ctx context.Context, id identity.Identity, f prototypes.SessionFilter, adminScoped bool) ([]prototypes.SessionRow, error)

type ListerProjectorOption ¶ added in v1.14.0

type ListerProjectorOption func(*ListerProjector)

ListerProjectorOption configures NewListerProjector.

func WithEnricher(e Enricher) ListerProjectorOption

type Option ¶

type Option func(*Service)

Option configures NewService.

func WithBus(b events.EventBus) Option

func WithEraser(e Eraser) Option

func WithLogger(l *slog.Logger) Option

func WithRedactor(r audit.Redactor) Option

func WithTitleSetter(ts TitleSetter) Option

type ProjectionEnricher ¶ added in v1.28.0

type ProjectionEnricher struct {
	// contains filtered or unexported fields
}

ProjectionEnricher is the projection-backed Enricher adapter: it serves the per-session counter rollup from the authoritative durable observability rollup projection (internal/observability/rollups) when that projection is CURRENT and its retained horizon COVERS the session's lifetime, and otherwise delegates explicitly to the existing raw CounterEnricher bounded scan — the honest fallback. The projection is used for EXACTLY the dimensions the projection is authoritative for (COST, TOKENS, and FAILED TASK OUTCOMES); the dimensions the projection does not model (total events emitted, total tasks spawned, and pending intervention) are read from the raw bounded scan, and the two are merged deterministically.

What the projection backs — and what it does NOT ¶

The rollup projection is an indexed materialization of the canonical event log's supported measures. Its measures are SOURCE-BACKED deltas, and the adapter never maps a measure onto a public counter whose meaning is broader than the measure's:

• TotalCostCents ← llm_cost_micros (exact integer micro-units of USD, converted to the existing whole-cent wire representation with ONE deterministic rounding at the end — sub-cent calls never floor to 0).
• TotalTokens ← llm_tokens_total.
• HasFailedTask ← tasks_failed > 0 (failed TERMINAL OUTCOMES).

The projection does NOT back events_count or tasks_count:

• llm_completions is the session's `llm.cost.recorded` successful-completion count — a SUBSET of the events the session emitted (task / pause / artifact / lifecycle events are not completions), so presenting it as total events_count would be a believable-but-false undercount.
• tasks_completed + tasks_failed + tasks_cancelled counts terminal OUTCOMES, not the tasks the session SPAWNED (running / paused tasks never produce a terminal outcome), so presenting it as total tasks_count would be a believable-but-false undercount too.

The canonical totals for those two counters — total events emitted and total spawned tasks — plus has_pending_intervention (the projection does not model the pause registry) are read through the existing raw bounded CounterEnricher fallback seam on EVERY projection-backed path. The raw scan's Partial flag rides along: a truncated event scan, an unreadable registry read, or an unreadable pause read makes the aggregate CounterStatus=partial, never current.

Deterministic merge — projection owns its three, raw owns the rest ¶

When the projection is current and covers the session, the adapter merges the two sources WITHOUT letting either overwrite the other's authoritative dimension: the projection's EXACT cost / tokens / failed-task values are never replaced by the raw scan's lower bounds, and the raw scan's canonical events / tasks / pending values are never replaced by a projection subset. The aggregate Partial is the raw scan's Partial — a partial raw dimension makes the whole rollup partial (its events / tasks / pending are honest lower bounds), and the projection-backed exact values ride along, never fabricated as current over an incomplete raw read.

Honest fallback — never missing data as exact zero ¶

When the projection cannot be trusted for the session — the quality read fails, the state is `catching_up` / `unavailable`, the session window cannot be resolved, the retained horizon starts after the session opened (a retention gap), or the projection query itself fails — the adapter delegates to the raw CounterEnricher bounded scan and returns that rollup VERBATIM (its own Partial marking rides along: a truncated scan or an unreadable registry read stays an honest lower bound). The fallback is never silent: every delegation is Warn-logged with the reason, and the projection's freshness stays observable through the adapter's Quality accessor. If the raw fallback cannot provide a trustworthy result under its own contract (an unavailable substrate, an unreadable registry), its honest zero-plus-Partial result is preserved — availability is never fabricated.

Freshness is observable ¶

"Current" is current-as-of-the-last-empty-read: a live runtime may persist an event a moment after that read (the projection moves to `catching_up` on its next advance), the same best-effort read-at-a-moment honesty the raw scan has. The adapter exposes the projection's Quality (state / watermark / retention) through Quality so wiring and operators can observe how fresh the served counters are.

Concurrent reuse (CLAUDE.md §5) ¶

A constructed *ProjectionEnricher is immutable after NewProjectionEnricher: it holds only the store / quality / fallback / window / clock / logger references, each itself safe for concurrent reuse. Every Counters call's per-run state lives in its arguments and locals; the adapter reads nothing from itself for run-specific data.

func NewProjectionEnricher(deps ProjectionEnricherDeps) (*ProjectionEnricher, error)

func (e *ProjectionEnricher) Counters(ctx context.Context, id identity.Identity, sessionID string) SessionCounters

func (e *ProjectionEnricher) Quality(ctx context.Context) (rollups.Quality, error)

type ProjectionEnricherDeps ¶ added in v1.28.0

type ProjectionEnricherDeps struct {
	// Store is the rollup projection's query surface the adapter reads the
	// session's authoritative cost / tokens / failed-task measures from
	// (identity-scoped by the query filter — the session's own triple,
	// never cross-session bleed).
	Store rollups.Store
	// Quality reads the projection's freshness (state / watermark /
	// retention). The adapter serves exact projection-backed counters only
	// when Quality reports StateCurrent AND the retained horizon covers the
	// session.
	Quality ProjectionQuality
	// Fallback is the existing raw CounterEnricher bounded scan. It is the
	// canonical source of the dimensions the projection does not model —
	// total events emitted, total spawned tasks, and pending intervention —
	// on the projection-backed path, and the adapter delegates to it
	// VERBATIM whenever the projection cannot be trusted for the session.
	// Its result's own honest Partial marking rides along in both cases —
	// never replaced by fabricated zeros or fabricated availability.
	Fallback Enricher
	// Window resolves the session's lifetime for the retention-coverage
	// proof.
	Window SessionWindowFunc
	// Clock supplies the window's "now". Nil routes to time.Now().UTC().
	Clock func() time.Time
	// Logger receives Warn-level diagnostics when the adapter falls back or
	// a read cannot be taken (the degradation is NEVER silent). Nil routes
	// to slog.Default().
	Logger *slog.Logger
}

ProjectionEnricherDeps carries the ProjectionEnricher's mandatory dependencies. Every dependency is required — a nil one would silently disable a dimension or the coverage proof (the exact silent-absence class this adapter closes), so NewProjectionEnricher fails loud rather than build a half-blind adapter (CLAUDE.md §5).

type ProjectionQuality ¶ added in v1.28.0

type ProjectionQuality interface {
	Quality(ctx context.Context) (rollups.Quality, error)
}

ProjectionQuality reads the rollup projection's operational freshness — the read-only surface the rollup projector exposes (Quality on the projector: completeness state, watermark, retained horizon). Wired to the production projector in assembly; tests supply a controllable fake.

type Projector ¶

type Projector interface {
	// ListSessions returns every session row visible to the caller,
	// already identity-scoped: when adminScoped is false the
	// implementation MUST restrict to the caller's own (tenant, user);
	// when true it MAY honour a cross-tenant TenantIDs filter. The
	// Service applies the facet filter + sort + pagination on top.
	ListSessions(ctx context.Context, id identity.Identity, f prototypes.SessionFilter, adminScoped bool) ([]prototypes.SessionRow, error)
	// InspectSession returns the full snapshot for sessionID, or
	// ErrSessionNotFound. adminScoped widens the lookup across tenants.
	InspectSession(ctx context.Context, id identity.Identity, sessionID string, adminScoped bool) (prototypes.SessionsInspectResponse, error)
	// CountersAvailable reports whether the projector populates the
	// numeric / boolean counters (cost / tokens / tasks / events /
	// intervention / failed-task). False when no counter Enricher is wired:
	// the Service then loud-rejects a facet / sort over those counters
	// rather than returning a false-empty page (WARN-3).
	CountersAvailable() bool
}

Projector is the read seam the Service depends on. The V1 production implementation is ListerProjector. Every method takes the verified identity triple plus the resolved admin-scope flag so the implementation scopes its reads.

type Service ¶

type Service struct {
	// contains filtered or unexported fields
}

Service implements the `sessions.*` Protocol methods. It is a safe for concurrent reuse compiled artifact — immutable after NewService.

func NewService(projector Projector, opts ...Option) (*Service, error)

func (s *Service) Delete(ctx context.Context, req prototypes.SessionsDeleteRequest) (prototypes.SessionsDeleteResponse, error)

func (s *Service) HasEraser() bool

func (s *Service) HasTitleSetter() bool

func (s *Service) Inspect(ctx context.Context, req prototypes.SessionsInspectRequest, adminScoped bool) (prototypes.SessionsInspectResponse, error)

func (s *Service) List(ctx context.Context, req prototypes.SessionsListRequest, adminScoped bool) (prototypes.SessionsListResponse, error)

func (s *Service) SetTitle(ctx context.Context, req prototypes.SessionsSetTitleRequest) (prototypes.SessionsSetTitleResponse, error)

type SessionCounters ¶ added in v1.14.0

type SessionCounters struct {
	// TasksCount is the number of tasks the session has spawned.
	TasksCount int
	// EventsCount is the number of events the session has emitted (a lower
	// bound when Partial is set).
	EventsCount int
	// TotalCostCents is the session's accumulated LLM cost in US cents (a
	// lower bound when Partial is set).
	TotalCostCents int64
	// TotalTokens is the session's accumulated LLM token count (a lower
	// bound when Partial is set).
	TotalTokens int64
	// HasPendingIntervention reports whether the session has a pause
	// awaiting resume / approval.
	HasPendingIntervention bool
	// HasFailedTask reports whether the session has at least one failed
	// task.
	HasFailedTask bool
	// Partial is true when ANY of the reads behind this rollup could not
	// be taken in full: the bounded per-session event scan hit its bound
	// (ListWindow HasMore / Truncated), the windowed-read substrate was
	// unavailable, or a registry read (tasks / pauses) failed or could not
	// be scoped to the row. Every populated count is then an HONEST LOWER
	// BOUND, not exact, and the facet/sort layer MUST NOT treat a Partial
	// key as authoritative.
	//
	// The marker covers the registry reads deliberately: a failed
	// registry read leaves TasksCount / HasFailedTask /
	// HasPendingIntervention at their zero values, and a zero that means
	// "we could not look" must never be reported as a zero that means
	// "we looked and there were none".
	Partial bool
}

SessionCounters is the read-time counter rollup for one session — the six false-absence SessionRow counters plus the honest-partial marker.

type SessionWindowFunc ¶ added in v1.28.0

type SessionWindowFunc func(ctx context.Context, id identity.Identity, sessionID string) (openedAt, lastActivityAt time.Time, ok bool, err error)

SessionWindowFunc resolves a session's lifetime window so the adapter can prove the projection's retained horizon covers the session before trusting the rollup as exact. Production wiring supplies a session-registry-backed resolver (the snapshot's OpenedAt / LastSeen); tests supply a fake. ok=false means the window could not be resolved — the adapter then CANNOT prove coverage and delegates to the raw fallback rather than guessing (unproven coverage is never treated as exact).

type SessionsAdminQueryPayload ¶

type SessionsAdminQueryPayload struct {
	events.SafeSealed
	// Actor is the verified admin identity at the Protocol edge — the
	// (tenant, user, session) triple the JWT carried.
	Actor identity.Identity
	// Method is the Protocol method that carried the cross-tenant query
	// (`sessions.list` or `sessions.inspect`).
	Method string
}

SessionsAdminQueryPayload is the typed SafePayload published on the canonical `audit.admin_scope_used` event when an operator runs a cross-tenant `sessions.list` / `sessions.inspect` query under the verified `auth.ScopeAdmin` claim.

SafePayload by construction: every field is a bounded identity component or a Protocol method name — no caller-supplied bytes reach the bus. The Sessions wire surface rejects malformed requests at the Protocol edge before the emit.

The payload is distinct from `auth.AdminScopeUsedPayload` ( impersonation), `events.AdminScopeUsedPayload` (Subscribe), and `toolsprotocol.ToolsAdminActionPayload` — all ride the same canonical `audit.admin_scope_used` event type, but each emit source declares its own typed payload. A subscriber type-switches.

type TitleSetter ¶ added in v1.12.0

type TitleSetter interface {
	// SetTitle sets or clears the title of session `id` for the CALLER's
	// verified `(tenant, user)` (`ident`). See sessions.SessionRegistry's
	// SetTitle for the full semantics (trim, validate, empty clears,
	// (tenant, user) write scope). Returns sessions.ErrInvalidTitle,
	// sessions.ErrSessionNotFound, or sessions.ErrIdentityMismatch on
	// refusal.
	SetTitle(ctx context.Context, id string, ident identity.Identity, title string) error
}

TitleSetter is the write seam the Service dispatches `sessions.set_title` to. The V1 production implementation is `*sessions.Registry` — its SetTitle method satisfies this interface directly (Registry already implements the wider SessionRegistry, of which SetTitle is one method). The Service depends ONLY on this narrow interface (CLAUDE.md §4.4) — a future remote / cross-runtime title-set slots in behind it without reshaping the Service.