protocol

type ApprovalChecker ¶ added in v1.14.0

type ApprovalChecker interface {
	// HasPendingApproval reports whether the task's run (scoped to the
	// task's own identity triple + run id) holds at least one open HITL /
	// tool-approval gate. Identity-scoped: session A's open gate never
	// bleeds into session B's row.
	HasPendingApproval(ctx context.Context, taskIdentity identity.Identity, runID string) bool
}

ApprovalChecker is the optional list-time seam RegistryProjector reads the per-row `HasPendingApproval` facet from. The task-registry record is a lifecycle record — it does NOT itself model "has an open approval gate"; that derived signal is owned by the pause/approval registry one package over (the tasks lifecycle-record model). Production wiring supplies an implementation backed by the pause coordinator scoped to the task's run; tests and partial builds run without one.

A projector with no ApprovalChecker wired leaves `HasPendingApproval` at its honest false — the projection-completeness gate's Half-B prod-wiring test proves production ALWAYS wires it (a forgotten `WithApprovalChecker` in mux.go would ship a permanently-false facet, the exact never-wired variant the gate closes).

type Enricher ¶

type Enricher interface {
	// ParentSession returns the parent-session reference card for the
	// task. A zero-valued ref is acceptable ("we don't have this data").
	ParentSession(ctx context.Context, id identity.Identity, taskID string) prototypes.TaskParentSessionRef
	// Cost returns the per-task cost rollup aggregated from
	// `llm.cost.recorded` events scoped to the task.
	Cost(ctx context.Context, id identity.Identity, taskID string) prototypes.TaskCostRollup
	// PlannerSnapshot returns the planner-checkpoint reference at task
	// spawn time, or nil when no checkpoint exists.
	PlannerSnapshot(ctx context.Context, id identity.Identity, taskID string) *prototypes.TaskPlannerSnapshotRef
	// Trajectory returns the projected reasoning-trace snapshot for the
	// task, or nil when the trajectory is unavailable (evicted, not
	// captured, or the run-loop has not wired a trajectory source).
	Trajectory(ctx context.Context, id identity.Identity, taskID string) *prototypes.TaskTrajectoryRef
}

Enricher is the optional per-task enrichment backend RegistryProjector reads parent-session / cost / planner-snapshot data through. Production wiring supplies an implementation backed by the sessions subsystem + the `llm.cost.recorded` event stream + the planner-checkpoint store; tests and partial-builds run without one.

type Option ¶

type Option func(*Service)

Option configures NewService.

func WithBus(b events.EventBus) Option

func WithLogger(l *slog.Logger) Option

func WithRedactor(r audit.Redactor) Option

type Projector ¶

type Projector interface {
	// ListTasks returns every task-row projection visible to id. The
	// Service applies the facet filter + pagination + aggregate
	// computation on top; the Projector returns the full identity-scoped
	// set, newest-first by StartedAt.
	ListTasks(ctx context.Context, id identity.Identity) ([]prototypes.TaskRow, error)
	// GetTask returns the enriched detail for taskID, or ErrTaskNotFound
	// when the task is not visible to id (cross-tenant lookups return
	// ErrTaskNotFound — existence is never revealed).
	GetTask(ctx context.Context, id identity.Identity, taskID string) (prototypes.TaskDetail, error)

	// ListTenantTasks returns task rows across ALL sessions of the named
	// tenants — the admin-widened FLEET read. It is invoked by Service.List
	// ONLY after the admin-scope gate passes; the implementation reads the
	// registry's explicit tenant-scoped enumeration seam. Every returned
	// row carries full per-(tenant, user, session) identity attribution so
	// a coordinator can attribute each row to its owning source. This is
	// the "future cross-runtime aggregating projector" the RegistryProjector
	// godoc reserved, landed behind the unchanged Projector interface.
	ListTenantTasks(ctx context.Context, tenantIDs []string) ([]prototypes.TaskRow, error)
}

Projector is the read seam the Service depends on. The V1 production implementation is RegistryProjector. Every method takes the verified identity triple so the implementation scopes its reads — the Service never trusts a Projector to apply identity itself; it passes the triple so the implementation scopes a per-tenant view.

type RegistryProjector ¶

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

RegistryProjector is the V1 production Projector — a read-only projection over a `tasks.TaskRegistry`. It maps the runtime-internal `tasks.Task` record onto the flat Protocol wire shapes the Console Tasks page renders.

Scope ¶

`tasks.TaskRegistry.List` is session-scoped: it returns the task summaries for one `(tenant, user, session)` identity. RegistryProjector projects the caller's own session — the realistic V1 surface, matching the high-cardinality runtime-side posture. A cross-tenant fan-in is gated by the Service (admin scope); the projector honours whatever identity the Service passes it. A future cross-runtime aggregating projector slots in behind the Projector interface without reshaping the Service.

Enrichment seam ¶

The TaskRegistry record carries lifecycle + identity + parent-task data, but NOT the parent-session metadata, the per-step cost rollup, or the planner-checkpoint reference. RegistryProjector reads those through the optional Enricher interface. When no Enricher is wired, `tasks.get` returns conservative zero-valued enrichment cards (an empty parent-session ref, a zero cost rollup, a nil planner snapshot) so a partial-build Console still renders the detail rather than failing — the zeros are honest ("we don't have this data"), not silent degradation of a known value.

Concurrent reuse ¶

RegistryProjector is immutable after NewRegistryProjector: it holds the registry + enricher references. The registry is itself safe for concurrent reuse; the projector adds no mutable state.

func NewRegistryProjector(registry tasks.TaskRegistry, opts ...RegistryProjectorOption) (*RegistryProjector, error)

func (p *RegistryProjector) GetTask(ctx context.Context, id identity.Identity, taskID string) (prototypes.TaskDetail, error)

func (p *RegistryProjector) ListTasks(ctx context.Context, id identity.Identity) ([]prototypes.TaskRow, error)

func (p *RegistryProjector) ListTenantTasks(ctx context.Context, tenantIDs []string) ([]prototypes.TaskRow, error)

type RegistryProjectorOption ¶

type RegistryProjectorOption func(*RegistryProjector)

RegistryProjectorOption configures NewRegistryProjector.

func WithApprovalChecker(c ApprovalChecker) RegistryProjectorOption

func WithEnricher(e Enricher) RegistryProjectorOption

type Service ¶

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

Service implements the two `tasks.*` read methods. It is a concurrency-safe compiled artifact — immutable after NewService.

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

func (s *Service) Get(ctx context.Context, req prototypes.TaskGetRequest) (prototypes.TaskDetail, error)

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

type TasksAdminActionPayload ¶

type TasksAdminActionPayload 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
	// fan-in (`tasks.list`).
	Method string
	// TenantCount is the number of distinct tenants the cross-tenant
	// `tasks.list` query named.
	TenantCount int
}

TasksAdminActionPayload is the typed SafePayload published on the canonical `audit.admin_scope_used` event when an operator issues a cross-tenant `tasks.list` fan-in (a query whose Filter.Identities names more than one distinct tenant).

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

The payload is distinct from `auth.AdminScopeUsedPayload` (the impersonation shape), `events.AdminScopeUsedPayload` (the Subscribe shape), and `ToolsAdminActionPayload`: all ride the same canonical `audit.admin_scope_used` event type, but each emit source declares its own typed payload (events.go §"Other emit sites ... MAY add new payload types"). A subscriber type-switches on the payload.