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.

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 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 the bounded per-session scan that produced the
	// cost / tokens / events counts hit its bound (ListWindow HasMore /
	// Truncated) or the windowed-read substrate was unavailable. The counts
	// are then an HONEST LOWER BOUND, not exact — the facet/sort layer MUST
	// NOT treat a Partial key as authoritative. TasksCount / HasFailedTask /
	// HasPendingIntervention (from the registries, not the bounded scan)
	// stay exact.
	Partial bool
}

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

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.