Lineage & activity

Two observability surfaces. LineageService answers “what has actually arrived, from where, and when” for each configured source, from the connector-run log. ActivityService streams what FACE’s agents are doing right now, including runs the caller did not start: scheduled fetches, other sessions, and long analyses.

Summary

Service	RPC	Kind	Purpose
LineageService	GetSourceActivity	Unary	Per-connection delivery activity over a window
ActivityService	SubscribeAgentActivity	Server streaming	Replay the in-flight runs, then stream live steps
ActivityService	ListFeaturedMessages	Unary	Operator-curated messages for the cockpit strip

LineageService

Full name semantics.v1.LineageService.

FACE records every connector extraction and delivery. A record holds the connection, the connector type, column names, row counts, the duration, a literal-free query shape and a closed-set error class. A lineage record, and so every answer here, never contains a result value, a driver’s error message, any part of a credential, or a query literal.

An answer does not show that a source is healthy, that data is flowing now, or that nothing arrived. When the deployment has no durable lineage store, only the newest few records are held in memory and are lost on restart. Check durable and show durable_reason whenever you show an empty or thin answer.

GetSourceActivity

rpc GetSourceActivity(GetSourceActivityRequest) returns (GetSourceActivityResponse);

Kind: Unary.
Auth: Bearer session.
Errors: UNAVAILABLE if the lineage log cannot be read. The message carries only the error class. It does not mean that no data arrived.

Folds the lineage records in the window into one row per connection, newest last_observed_unix first.

Request: GetSourceActivityRequest

Field	Type	Description
`window_days`	`int32`	How far back to look. 0, a negative value, or more than the retention period means the full retention period.
`connection_id`	`string`	One connection. Empty means every connection.

Response: GetSourceActivityResponse

Field	Type	Description
`sources`	`repeated` `SourceActivity`	One entry per connection with records in the window, newest first.
`durable`	`bool`	Whether these records survive a restart. `false` means an in-memory ring, so an empty answer may say more about this process’s uptime than about the sources.
`durable_reason`	`string`	The sentence to show about durability.
`window_since_unix`	`int64`	Start of the window actually read, which may be shorter than requested.
`window_until_unix`	`int64`	End of the window (now).
`records_read`	`int32`	Records in the window before folding. 0 with no sources means nothing was recorded in this window.

ActivityService

Full name semantics.v1.ActivityService.

SubscribeAgentActivity

rpc SubscribeAgentActivity(SubscribeAgentActivityRequest) returns (stream SubscribeAgentActivityResponse);

Kind: Server streaming. Available over native gRPC and gRPC-web.
Auth: Bearer session.
Errors: None of its own. The stream ends when the client cancels.

When the stream opens, the server first replays current state. It sends one snapshot event for every in-flight run in scope, each with its most recent steps, then one snapshot_complete event. After that it streams live run_started, step and run_finished events. Render nothing until snapshot_complete arrives, so that a client joining mid-run does not show a partial picture.

Scope. Only runs whose session matches are streamed. The session is session from the request or, when that is empty, the caller’s x-agent-trace-id metadata. A run carries the trace id of the client that started it, so a client that sets the header on every call sees its own runs. When both are absent, the stream is ambient and covers every agent run on the instance, which is what an operator console wants.

Limits. A run keeps its last 100 steps. Every free-text field and operand value is truncated to 240 characters. Each subscriber has a buffer of 256 events. A subscriber that stops reading loses the events that do not fit, and the run itself is not affected. At most 64 runs are tracked in flight.

Request: SubscribeAgentActivityRequest

Field	Type	Description
`replay_steps_per_run`	`int32`	Maximum trailing steps per run in the initial replay. 0 or negative means 20.
`session`	`string`	Show only runs from this session. Empty falls back to the `x-agent-trace-id` metadata. Ambient only when both are absent.

Response: SubscribeAgentActivityResponse

Exactly one of the event fields is set.

Field	Type	Description
`snapshot`	`AgentRun`	oneof `event`. One per in-flight run when the stream opens, with its recent `steps`.
`snapshot_complete`	`bool`	oneof `event`. Marks the end of the replay.
`run_started`	`AgentRun`	oneof `event`. A run began.
`step`	`AgentStep`	oneof `event`. A run recorded a step.
`run_finished`	`AgentRun`	oneof `event`. A run ended. See `status` and `error`.

ListFeaturedMessages

rpc ListFeaturedMessages(ListFeaturedMessagesRequest) returns (ListFeaturedMessagesResponse);

Kind: Unary.
Auth: Bearer session.
Errors: None beyond authentication. If the operator has provided no message file, or the file is unreadable or not a JSON array, the response has no messages and a diagnostic source.

Returns the operator-curated cards the cockpit cycles through. The operator edits them on the deployment, without a rebuild. Messages with neither a title nor a body are skipped.

Request: ListFeaturedMessagesRequest

No fields.

Response: ListFeaturedMessagesResponse

Field	Type	Description
`messages`	`repeated` `FeaturedMessage`	The messages, in file order.
`source`	`string`	Where the server read them from, for an operator diagnosing an empty strip. Diagnostic only. Do not parse or display it to end users.

Messages

SourceActivity

What one configured source did over the window.

Field	Type	Description
`connection_id`	`string`	Connection id.
`connection_name`	`string`	Connection name.
`connector_type`	`string`	Normalised connector type, for example `postgres` or `mqtt`.
`environment`	`string`	Environment label of the connection.
`runner`	`string`	The runner that executed the runs.
`last_observed_unix`	`int64`	Latest record in the window. 0 means no record in the window, not “has never delivered”.
`first_observed_unix`	`int64`	Earliest record in the window.
`extractions`	`int32`	Extraction runs observed.
`deliveries`	`int32`	Records of data actually landing somewhere.
`rows`	`int64`	Rows summed across deliveries.
`ok`	`int32`	Runs that succeeded with data.
`empty`	`int32`	Runs that connected and received nothing. This is neither a failure nor a delivery.
`failed`	`int32`	Runs that failed.
`error_classes`	`repeated string`	Closed-set error classes, present when `failed` is non-zero. Never a driver message.
`last_duration_ms`	`int64`	Duration of the last run, when one was observed.
`destinations`	`repeated` `LineageDestination`	Where this source’s data went. Empty means extractions were seen but no delivery was recorded.
`last_columns`	`repeated string`	Column names from the last extraction. Names only, never values.

LineageDestination

Field	Type	Description
`kind`	`string`	Destination kind, for example `recordstore` or `objectstore`.
`id`	`string`	Destination id.
`name`	`string`	Destination name.
`movements`	`int32`	Deliveries to this destination.
`rows`	`int64`	Rows delivered.
`first_seen_unix`	`int64`	First delivery in the window.
`last_seen_unix`	`int64`	Last delivery in the window.

AgentRun

One agent execution.

Field	Type	Description
`run_id`	`string`	Run id. For an orchestrator run started with a `thread_id`, it is that thread id.
`agent`	`string`	Agent id, for example `posture`, `fetch-cascade` or `ralph:twins`.
`session`	`string`	Session (trace id) of the client that started the run.
`started_unix`	`int64`	Start time.
`ended_unix`	`int64`	End time. 0 while in flight.
`status`	`AgentRunStatus`	Lifecycle state.
`step_count`	`int32`	Steps recorded so far.
`steps`	`repeated` `AgentStep`	Set only on `snapshot` events, bounded by `replay_steps_per_run`. Live steps arrive as `step` events.
`error`	`string`	Set when `status` is `AGENT_RUN_STATUS_FAILED`.

AgentStep

One iteration of an agent loop.

Field	Type	Description
`run_id`	`string`	The run this step belongs to.
`index`	`int32`	Step index within the run.
`thought`	`string`	Reasoning text. Often empty: phase-style runs such as the fetch cascade record only action and result.
`action`	`string`	What the step did.
`input`	`string`	Step input.
`result`	`string`	Step result.
`model`	`string`	Model that served the step, if any.
`latency_ms`	`int64`	Step latency.
`error`	`string`	Non-empty when the step failed. A failed step does not necessarily fail the run.
`at_unix`	`int64`	When the step was recorded.
`code`	`string`	Stable, machine-readable step kind, for example `STEP_ANALYSING` or `STEP_MODEL_THOUGHT`. Compose the display line from it in your own locale. `STEP_MODEL_THOUGHT` is the one code whose text the model wrote. Empty is permanently valid: fall back to `action`. Render nothing for a code you do not recognise, never the raw token.
`operands`	`map<string, string>`	Facts the backend observed for `code`, such as counts and names. Provenance is included under `provenance_source`, `provenance_degraded` and `provenance_computed_at`. A missing operand should degrade the line, not drop the step.

FeaturedMessage

Field	Type	Description
`id`	`string`	Message id.
`title`	`string`	Title.
`body`	`string`	Body text.
`locale`	`string`	BCP-47 tag, for example `en` or `pt-BR`. Empty means any locale.
`href`	`string`	Optional link target.
`icon`	`string`	Optional semantic icon name for the client to map to its own icons. Never a URL.

Enums

AgentRunStatus

Value	Meaning
`AGENT_RUN_STATUS_UNSPECIFIED`	Not set.
`AGENT_RUN_STATUS_RUNNING`	In flight.
`AGENT_RUN_STATUS_DONE`	Finished.
`AGENT_RUN_STATUS_FAILED`	Failed. See `error`.

SQL CCTV, surveillance & documents