Skip to content

AI and platform

Model access, the agent-activity feed, sign-in, the business profile and self-healing status. Package pulse.v1; the least role of each method is in its table.

Notes

  • ModelService is the door to the platform’s own inference plane. There is no third-party model behind it.
  • ActivityService. A subscriber receives only its own runs; a run no account started (a schedule, an inbound message) reaches nobody. Render nothing for an unknown non-empty AgentStep.code, never the raw token; an empty code is valid, so fall back to thought and action. See Agent activity.
  • IdentityService. expires_in is in seconds. Refresh, Google sign-in and sign-out are plain HTTP; see HTTP endpoints.

ModelService

AI model proxy — completion endpoint to the configured local inference engine (mistral.rs’s mistralrs-server).

pulse.v1.ModelService, declared in pulse.proto.

MethodRequest → ResponseLeast roleNotes
CompleteCompleteRequest → stream StreamChunkeditorComplete streams a completion from the configured inference engine.
GetModelStatusgoogle.protobuf.Empty → ModelStatusnone (public)GetModelStatus returns current model health/readiness.
SynthesizeSpeechSynthesizeSpeechRequest → SynthesizeSpeechResponseviewerSynthesizeSpeech turns text into spoken audio and returns the WAV bytes. Synthesis goes through TIDE’s shared ttsd service over HTTP (grpc/internal/speech; endpoint TTSD_URL, unset = the in-cluster Service, empty = voice output disabled -> Unavailable), purpose “readback”. PULSE embeds no TTS engine. TTS_REMOTE_URL, which this comment once named, is read NOWHERE in the server.
ConfirmAssistantActionConfirmAssistantActionRequest → stream AssistantActionEventeditorConfirmAssistantAction runs a proposal the assistant made in Complete, after the user tapped Confirm. The server re-checks the caller’s role and the stored arguments; an expired, used or someone else’s proposal is refused. Nothing here sends email, posts or calls.

Also uses StreamChunk, AssistantToolEvent, AssistantProposal.

message ConfirmAssistantActionRequest {
  string proposal_id = 1;
}

message AssistantActionEvent {
  string status = 1;       // running | done
  string detail = 2;       // a progress line from the action, or its result
  string route = 3;        // the page that shows the result
  string audit_domain = 4; // set when an audit started: the chat shows its progress card
  string result_id = 5;    // id of the record created or changed, when there is one
}

message SynthesizeSpeechRequest {
  string text = 1;
  string voice = 2; // optional voice id; engine default when empty
}

message SynthesizeSpeechResponse {
  bytes audio = 1;
  string format = 2; // e.g. "wav"
}

message ChatMessage {
  string role = 1;    // "system", "user", "assistant"
  string content = 2;
  // Text files the person attached to THIS question (logs, exports), on the
  // latest user message only. UNTRUSTED DATA: the server hides credentials
  // again, screens and fences each as data (assistant_attachments.go), and
  // refuses a request over a limit.
  repeated ChatAttachment attachments = 3;
  // Pictures (screenshots, photos of a screen or a page) the person attached to
  // THIS question, on the latest user message only. UNTRUSTED: the server
  // re-encodes each as a metadata-free JPEG, has the vision tier describe it,
  // hides credentials in the description and fences it as data
  // (assistant_images.go). Nothing is stored. At most 3; each at most 1 MiB, all
  // together at most 2500 KiB; a request over a limit is refused with a sentence.
  repeated ChatImage images = 4;
}

// ChatImage is one attached picture: JPEG or PNG bytes.
message ChatImage {
  string name = 1;
  string mime = 2;
  bytes data = 3;
}

// ChatAttachment is one attached text file.
message ChatAttachment {
  string name = 1;
  string text = 2;
}

message CompleteRequest {
  string prompt = 1;                   // simple prompt (use messages for multi-turn)
  repeated ChatMessage messages = 2;   // multi-turn conversation
  double temperature = 3;
  double top_p = 4;
  int32 max_tokens = 5;
  string agent_id = 6;                // which agent profile to use
  // Variables substituted into the agent's system prompt via Go's
  // text/template ({{.key}} syntax — see buildAgentSystemPrompt and
  // agents/templates/*.jinja's default_system_message blocks). Also
  // differentiates the dedup cache key (see dedupKeyFor) even for agents
  // whose prompt doesn't reference a given var.
  map<string, string> template_vars = 7;
}

message ModelStatus {
  bool ready = 1;
  string model_name = 2;
  int64 context_size = 3;
  int32 active_requests = 4;
  double uptime_seconds = 5;
  string error = 6;
}

ActivityService

ActivityService is the agent-activity plane: what the CALLER’s agents are doing right now, across every page and tab, not only the one that started them.

AUTHORISATION IS OWNERSHIP. Every run is stamped server-side with the authenticated user of the request that caused it; a subscriber receives a run (replayed or live) only when that owner is its own authenticated identity. Runs with no owner (schedules, webhooks, A2A) are delivered to nobody. The session below is a filter within the caller’s own runs, never authorisation.

WHY THIS EXISTS. PULSE’s generation RPCs stream to their own caller, so a long job is legible only on the screen that launched it. A 15-page whitepaper is minutes of decode on the shared CPU inference plane, and every other page — and every other tab — shows nothing at all. The steps were already being recorded: modelServer.recordInference builds a costed telemetry.RunTrace for every generation (model, tokens, latency, provenance) and hands it to the health reporter. No RPC exposed them, so the cockpit could not show them.

Mirrors FACE’s service of the same name deliberately: same shapes, same replay contract, so the two cockpits can share a mental model and, later, a widget.

pulse.v1.ActivityService, declared in activity.proto.

MethodRequest → ResponseLeast roleNotes
SubscribeAgentActivitySubscribeAgentActivityRequest → stream SubscribeAgentActivityResponseviewerSubscribeAgentActivity streams agent runs and their steps as they happen. ON SUBSCRIBE IT REPLAYS THE CURRENT STATE FIRST — every in-flight run, each with the steps recorded so far — before any live event, terminated by snapshot_complete. A client that only saw future events would show nothing to someone who opened the page mid-run, which is the whole failure this plane exists to end. Keying off current state rather than a transition is the rule here.
ListFeaturedMessagesListFeaturedMessagesRequest → ListFeaturedMessagesResponseviewerListFeaturedMessages returns the operator-curated messages the cockpit cycles through — sponsor and partner copy. Served from a file the deployment can mount, so it changes without rebuilding the app.
message SubscribeAgentActivityRequest {
  // Cap on how many trailing steps the initial replay carries per run. 0 uses
  // the server default.
  int32 replay_steps_per_run = 1;

  // Show only those of the caller's OWN runs belonging to this session.
  //
  // Empty here falls back to the caller's `x-agent-trace-id` metadata, so a
  // client that forgets this field is still narrowed to its own tab. With BOTH
  // absent the subscription is every run the caller owns — never anyone
  // else's, whatever session is or is not sent.
  //
  // WHY THIS EXISTS (FACE's rationale, which applies verbatim here — see
  // face/grpc/api/proto/semantics/v1/activity.proto). Ambient-for-everyone was
  // the wrong default for the CUSTOMER cockpit. Every page rendered the same
  // card for a run nobody on that device had started, so the card and the page
  // contradicted each other: a centre said "nothing has run on this device yet"
  // while the card beneath it showed an agent mid-flight. Two true statements
  // about two different scopes, stacked, reading as a bug.
  //
  // THE EMITTER HALF IS LIVE TOO, WHICH IS WHAT MAKES THIS FIELD USABLE. Every
  // PULSE run started from a request carries the caller's trace id:
  // model_server.go's startInference (the streaming and the structured
  // generation paths), the assistant's grounding phase, both editorial-guard
  // phases (model_server.go and egress.go), and the diagnostic's grounding
  // phase. That last one used to pass its own diagnosticID, which was the wrong
  // identifier for the same reason a run id would be — the cockpit subscribes
  // ONCE for the whole card, so a run stamped with a per-job identity is matched
  // by no subscriber and disappears from the card of the person who started it.
  //
  // A RUN WITH NO SESSION IS NOT SEEN BY A SCOPED CLIENT. Work started off a
  // context detached from any request — a schedule, a WhatsApp inbound, A2A,
  // the autonomous media buyer — has no cockpit behind it, so it carries no
  // session, and no authenticated caller, so it has no owner and reaches no
  // subscriber at all. The hub gives a scoped subscriber only its OWN runs:
  // "unattributed" and "somebody else's" are one bucket, not two. That is FACE's
  // rule as well, and it is what stops a customer's card showing an agent
  // mid-flight under a page that correctly says nothing has run on this device.
  // The cost is that an emitter which forgets to thread the session makes its
  // runs vanish rather than leak — a quiet failure, which is why every emitter
  // is pinned by test (activity_wire_test.go).
  string session = 2;
}

enum AgentRunStatus {
  AGENT_RUN_STATUS_UNSPECIFIED = 0;
  AGENT_RUN_STATUS_RUNNING = 1;
  AGENT_RUN_STATUS_DONE = 2;
  AGENT_RUN_STATUS_FAILED = 3;
}

// AgentStep mirrors mesh/telemetry.Step — one unit of agent work.
//
// PULSE has no multi-step ReAct loop, so a generation is ONE step and `thought`
// is normally empty; the useful fields here are model, tokens and latency. A
// renderer must not assume every step narrates itself.
message AgentStep {
  string run_id = 1;
  int32 index = 2;
  string thought = 3;
  string action = 4;
  string input = 5;
  string result = 6;
  string model = 7;
  int64 latency_ms = 8;
  string error = 9;
  int64 at_unix = 10;
  int64 total_tokens = 11;

  // The step's STABLE, MACHINE-READABLE kind — one of the ~20 tokens in
  // mesh/telemetry/stepcode.go, e.g. "STEP_DISPATCHED".
  //
  // WHY A CODE AND NOT A SENTENCE. A sentence written in Go cannot be
  // translated by a Flutter client: this app ships four locales and an English
  // string that arrived over the wire is useless in three of them. A code also
  // makes the TRUST LEVEL legible — a renderer can badge STEP_MODEL_THOUGHT as
  // the model's own words and treat STEP_FINISHED as an observed fact, which is
  // impossible when both arrive as prose in the same field.
  //
  // EMPTY IS VALID AND PERMANENT: a legacy step, for which a renderer falls
  // back to thought/action. An UNKNOWN non-empty code must render NOTHING —
  // never the raw token. `STEP_ESCALATED` on a customer's screen is the same
  // class of defect as `pulse:copywriter` as an agent name, which is what this
  // whole change exists to end.
  string code = 12;

  // The backend-observed facts `code` declares (stepcode.go's
  // RequiredOperands). Every value already existed in a variable at the call
  // site: nothing estimated, nothing inferred from elapsed time, nothing read
  // off the model's own output.
  //
  // "Required" is a contract with the CLIENT, not a runtime assertion. A
  // missing operand must DEGRADE the rendered line, never drop the step —
  // observability that can break the thing it observes is worse than none.
  //
  // Some values are DATA rather than vocabulary: `examples` is quoted model
  // output, `target` is a caller's URL, `thought` is the model's own words. A
  // client interpolates those verbatim and never translates them.
  map<string, string> operands = 13;

  // How the answer this step reports was produced — mirrors
  // mesh/telemetry.Provenance, which every recordInference already builds and
  // which NO card has ever rendered because no AgentStep proto carried it.
  //
  // Absent when the step has none. Present-and-fresh is the healthy case and a
  // renderer is expected to stay silent about it (TIDE's provenance layer:
  // "silence means measured" — stamping LIVE on every row of a healthy screen
  // trains the eye to skip the strip). It gets loud on a reused, offline or
  // degraded answer, which is exactly when a reader needs to know.
  StepProvenance provenance = 14;
}

// StepProvenance is the wire copy of mesh/telemetry.Provenance.
//
// Only the three fields a card can honestly render are carried. `model` is
// already AgentStep.model, and `confidence` is omitted because nothing in PULSE
// populates it — a chip showing 0.00 would make an unset field look like a
// measured score.
message StepProvenance {
  // How it was obtained: "fresh" | "exact-cache" | "near-dup" | "offline".
  // Unknown values must degrade to "no claim", never render raw.
  string source = 1;
  // The cascade rung that produced it, e.g. "full", "exact-cache". Diagnostic
  // detail for a tooltip; never the primary label.
  string path = 2;
  // Produced without full server capability. A reader should weight it lower.
  bool degraded = 3;
  // When the underlying value was produced. For a REUSED result this is the
  // ORIGINAL computation time, which is the whole point: it exposes staleness.
  // Zero means unknown — not "now".
  int64 computed_at_unix = 4;
}

message AgentRun {
  string run_id = 1;
  // The recorder's agent id, e.g. "pulse:whitepaper".
  string agent = 2;
  string session = 3;
  int64 started_unix = 4;
  // Zero while the run is still in flight.
  int64 ended_unix = 5;
  AgentRunStatus status = 6;
  int32 step_count = 7;
  // Populated only on the initial replay, bounded by replay_steps_per_run.
  repeated AgentStep steps = 8;
  string error = 9;
}

message SubscribeAgentActivityResponse {
  oneof event {
    AgentRun snapshot = 1;
    // Marks the end of the replay. A client renders nothing until it arrives,
    // so a mid-run subscriber never paints a partial picture and then jumps.
    bool snapshot_complete = 2;
    AgentRun run_started = 3;
    AgentStep step = 4;
    AgentRun run_finished = 5;
  }
}

message ListFeaturedMessagesRequest {}

// FeaturedMessage is one operator-curated card in the cockpit's rotating strip:
// sponsor and partner copy.
//
// NOT localized through the app's ARB catalog, unlike the assistant panel's
// built-in prompt tips. Sponsor copy is edited against a deployed instance, so
// it cannot live in a bundle that requires a rebuild — which is the whole
// reason this is an RPC rather than another l10n key.
message FeaturedMessage {
  string id = 1;
  string title = 2;
  string body = 3;
  // BCP-47 tag, e.g. "en", "pt-BR". Empty means "any locale".
  string locale = 4;
  // Optional link target. The client decides whether to make the card tappable.
  string href = 5;
  // Optional icon hint: a semantic name the client maps to its own icon set,
  // never a URL, so the card renders with no network fetch and no CSP surface.
  string icon = 6;
}

message ListFeaturedMessagesResponse {
  repeated FeaturedMessage messages = 1;
  // Where the server read them from, for the operator's benefit when the strip
  // is unexpectedly empty. Diagnostic only; the client must not parse it.
  string source = 2;
}

IdentityService

Authentication — JWT-based login/logout.

pulse.v1.IdentityService, declared in pulse.proto.

MethodRequest → ResponseLeast roleNotes
LoginLoginRequest → LoginResponsenone (public)Login authenticates a user and returns a JWT token.
Logoutgoogle.protobuf.Empty → google.protobuf.Emptyany signed-inLogout invalidates the current session/token.
GetCurrentUsergoogle.protobuf.Empty → Userany signed-inGetCurrentUser returns the authenticated user’s profile.
DeleteAccountDeleteAccountRequest → DeleteAccountResponseany signed-inDeleteAccount deletes the caller’s own account: every row PULSE keeps under it, its sessions and its sign-in (Google Play account deletion). confirm_email must be the account’s email. The break-glass admin and the deployment’s only admin are refused (FailedPrecondition).

Also uses User.

message LoginRequest {
  string username = 1;
  string password = 2;
}

message LoginResponse {
  string access_token = 1;
  string refresh_token = 2;
  User user = 3;
  int64 expires_in = 4; // seconds until token expiry
}

message DeleteAccountRequest {
  // The account's email, typed by the person to confirm.
  string confirm_email = 1;
}

message DeleteAccountResponse {
  // Rows deleted across every table that keeps the account's id.
  int64 rows_deleted = 1;
}

ConfigService

Application configuration management.

pulse.v1.ConfigService, declared in pulse.proto.

MethodRequest → ResponseLeast roleNotes
GetConfigGetConfigRequest → AppConfigviewerGetConfig returns the current application configuration.
UpdateConfigUpdateConfigRequest → AppConfigeditorUpdateConfig updates the application configuration.

Also uses Channel.

message GetConfigRequest {
  string user_id = 1;
}

message AppConfig {
  string id = 1;
  string user_id = 2;
  string business_name = 3;
  string industry = 4;
  string default_language = 5;
  string default_tone = 6;
  repeated Channel active_channels = 7;
  string timezone = 8;
  map<string, string> preferences = 9; // generic key-value preferences
  google.protobuf.Timestamp updated_at = 10;
}

message UpdateConfigRequest {
  string business_name = 1;
  string industry = 2;
  string default_language = 3;
  string default_tone = 4;
  repeated Channel active_channels = 5;
  string timezone = 6;
  map<string, string> preferences = 7;
}

SelfHealService

Read-only window into the in-process self-healing loop (cmd/self_healing.go, mesh/selfheal): a Watchdog + Remediator that already runs in every PULSE deployment but had no way for an operator to see it working. GetStatus is the only RPC — this service observes, it never triggers remediation itself.

pulse.v1.SelfHealService, declared in pulse.proto.

MethodRequest → ResponseLeast roleNotes
GetStatusgoogle.protobuf.Empty → SelfHealStatusviewer
message SelfHealEvent {
  string type = 1;        // HealthEventType, e.g. "endpoint_unhealthy", "memory_pressure"
  string severity = 2;    // e.g. "warning", "critical"
  string target_id = 3;
  string description = 4;
  bool remediated = 5;    // true if the remediator handled it without error
  google.protobuf.Timestamp at = 6;
}

message SelfHealStatus {
  bool healthy = 1;               // no critical event unresolved in the recent window
  google.protobuf.Timestamp started_at = 2;
  SelfHealEvent last_event = 3;   // unset if nothing has fired yet
  repeated SelfHealEvent recent_events = 4; // most recent first, bounded
  int32 remediation_attempts = 5;
  int32 remediation_failures = 6;
}