chain-client-sdk-ts/proto/chain/v1/hub.proto
flemming-it 1e02f1473f
Some checks failed
CI / Type-check and hermetic tests (push) Successful in 46s
CI / Skew — this client against a released hub (push) Failing after 2s
chore(proto): re-sync the chain.v1 copies after the evidence RPCs
Signed-off-by: flemming-it <sf@flemming.it>
2026-10-31 02:21:11 +01:00

1914 lines
71 KiB
Protocol Buffer

syntax = "proto3";
package chain.v1;
import "google/protobuf/empty.proto";
import "chain/v1/common.proto";
// The Hub service is what CLI clients, web UIs, or other tools talk to.
service Hub {
// Submit a flow for execution.
rpc Submit(SubmitRequest) returns (SubmitResponse);
// Submit a flow and follow its execution live (added 1.1). Same
// request as unary Submit; the response is a stream of step markers,
// ephemeral module events (host.emit-event), and finally the result
// or an error. Works over native gRPC and gRPC-Web (server
// streaming). Unary Submit is unchanged for clients that don't care.
rpc SubmitStream(SubmitRequest) returns (stream SubmitStreamEvent);
// List modules known to this hub.
rpc ListModules(google.protobuf.Empty) returns (ModuleList);
// Detached-invocation lifecycle (added 1.1). Only invocations
// submitted with detach=true are tracked; results are retained under
// hard operator limits (size/count/TTL) and NOT persisted across a
// hub restart.
rpc GetInvocationStatus(InvocationId) returns (InvocationStatus);
rpc GetInvocationResult(InvocationId) returns (SubmitResponse);
rpc CancelInvocation(InvocationId) returns (CancelInvocationResponse);
// List every tracked detached invocation (newest-first) for a
// monitor surface — Studio's detached-runs list. Returns an empty
// list (not an error) when detached invocations are disabled.
rpc ListInvocations(google.protobuf.Empty) returns (InvocationList);
// Liveness / readiness probe.
rpc Health(google.protobuf.Empty) returns (HealthStatus);
}
// HubAdmin exposes administrative operations on the hub: inspect
// installed modules, query the event log, manage saved flows.
//
// Calls to HubAdmin from external clients are unauthenticated in
// Phase 0/0.5 (localhost trust). Phase 1+ adds bearer-token / mTLS
// auth on this surface. Calls from within modules require the
// `hub:` permission scope (read / install / admin).
service HubAdmin {
// List capabilities provided by all installed modules.
rpc ListCapabilities(google.protobuf.Empty) returns (CapabilityList);
// Return full manifest data for one installed module.
rpc ModuleInfo(ModuleInfoRequest) returns (ModuleInfoResponse);
// Check whether a module is allowed a given permission under the
// operator's policy. Returns the decision plus the reason.
rpc CheckPermission(CheckPermissionRequest) returns (CheckPermissionResponse);
// Read a slice of the event log, newest first.
rpc EventLog(EventLogRequest) returns (EventLogResponse);
// Server-streaming variant of EventLog. The hub first emits up
// to `limit` historical events (newest-last so clients receive
// them in chronological order), then keeps the stream open and
// forwards every freshly-appended event in real time. Reads
// require the Read scope when auth is on.
rpc StreamEvents(StreamEventsRequest) returns (stream LoggedEvent);
// Saved-flow management. A saved flow is a YAML file under
// <data_dir>/flows/<name>.yaml; it can be re-run by name later.
rpc SaveFlow(SaveFlowRequest) returns (SaveFlowResponse);
rpc DeleteFlow(DeleteFlowRequest) returns (DeleteFlowResponse);
rpc ListFlows(google.protobuf.Empty) returns (FlowList);
rpc RunSavedFlow(RunSavedFlowRequest) returns (SubmitResponse);
// Return the parsed structure of a saved flow (declared
// inputs + their type tags) so a client can render an
// input form before calling RunSavedFlow.
rpc GetFlowDefinition(GetFlowDefinitionRequest) returns (FlowDefinition);
// List the shared hub's project registry (`general` first) —
// the lightweight labels that group flows, runs, approvals and
// audit events. Only `open` and `protected` projects appear:
// sealed projects are their own hub instance and are never
// known to a shared hub (docs/architecture/projects.md).
// Studio's workspace switcher reads this list.
rpc ListProjects(google.protobuf.Empty) returns (ProjectList);
// Search the bundled (and Phase 1+: federated) store index for
// modules matching a query.
rpc SearchStore(SearchStoreRequest) returns (StoreSearchResponse);
// List the configured module stores (operator config `stores:`)
// plus the implicit bundled seed, for the Studio store manager.
rpc ListStores(ListStoresRequest) returns (ListStoresResponse);
// Register a new module store and merge its index into the live
// store so its modules become searchable + installable immediately.
rpc AddStore(AddStoreRequest) returns (AddStoreResponse);
// Drop a configured store by name and rebuild the live index
// without it. The bundled seed cannot be removed.
rpc RemoveStore(RemoveStoreRequest) returns (RemoveStoreResponse);
// Install a module from a .chain bundle (local path or http(s) URL).
rpc InstallModule(InstallModuleRequest) returns (InstallModuleResponse);
// Same install, with live progress. Emits an update per phase and,
// during the download, as bytes arrive; the last message carries
// either the finished response or the error. Clients that only need
// the outcome keep using the unary InstallModule above — this exists
// so a waiting operator can see that a slow download is progressing
// rather than hung.
rpc InstallModuleStream(InstallModuleRequest)
returns (stream InstallProgressEvent);
// Remove an installed module by name. Wipes the module
// directory and re-scans the registry; writes a
// `module.uninstalled` audit event. Surfaced by the Studio
// module sheet's "Uninstall" affordance.
rpc UninstallModule(UninstallModuleRequest) returns (UninstallModuleResponse);
// Fetch a module's README (or other docs) and return the
// markdown content as a string. The hub knows how to
// authenticate against the configured registry — Studio
// doesn't need to handle credentials. Studio's Store detail
// sheet renders the result inline.
rpc FetchModuleDocs(FetchModuleDocsRequest) returns (FetchModuleDocsResponse);
// Read the inline-docs (MODULE.md / MODULE.<locale>.md) of an
// installed module from disk. No network fetch, no provider-
// specific URL probing — the docs ship in the .chain bundle and
// live next to module.wasm on disk after install. Returns an
// empty body when the module is installed but ships no inline
// docs; Studio uses that to hide the docs button entirely.
rpc GetInstalledModuleDocs(GetInstalledModuleDocsRequest) returns (GetInstalledModuleDocsResponse);
// Invoke an installed Studio plugin's `theme` hook. Returns
// the plugin's proposed Material 3 ColorScheme for the
// brightness the caller asked for ("light" or "dark"). The
// first end-to-end RPC of the Studio-plugin subsystem; the
// `translate` and `output-view` hooks get their own RPCs as
// the matching Studio surfaces ship.
rpc InvokePluginTheme(InvokePluginThemeRequest) returns (InvokePluginThemeResponse);
// Invoke an installed Studio plugin's `translate` hook.
// The first user surface that consumes this is Studio's
// FaiEnBadge — when an operator has a translate plugin
// installed, server-supplied English text (MCP tool
// descriptions, n8n endpoint names) gets translated
// on-the-fly into the active locale instead of carrying
// the honest-but-rough [EN] badge.
rpc InvokePluginTranslate(InvokePluginTranslateRequest) returns (InvokePluginTranslateResponse);
// List system.approval@^0 entries, optionally filtered by status.
rpc ListApprovals(ListApprovalsRequest) returns (ApprovalList);
// Reviewer decision on a pending approval. `decision` selects
// approve / reject; `reviewer` and `reason` supply the audit
// attribution. The flow that posted the approval resumes (or
// fails) on the next polling tick.
rpc DecideApproval(DecideApprovalRequest) returns (DecideApprovalResponse);
// Walk the event-log hash chain and return whether tampering
// was detected. Surfaced by the CLI as `chain admin verify-events`
// and by Studio's health page.
rpc VerifyEventChain(google.protobuf.Empty) returns (VerifyEventChainResponse);
// Wipe every audit event and seed the log with a single
// `chain.reset` marker. Refused on `beta` / `production` for
// compliance — only callable on `local` / `dev`. Surfaced by
// the CLI as `chain admin events clear`.
rpc ClearEventLog(ClearEventLogRequest) returns (ClearEventLogResponse);
// Append events that happened OUTSIDE this hub to the audit
// chain: an application records its own decision trail here so a
// third party can check it against the hash chain, the actor
// signatures and the head anchors. Each event carries an
// idempotency key that is unique within its project, so a
// repeated submission answers with the first event id instead of
// appending twice. Narrow scope `record` (optionally
// `record:<project>`); `admin` is a superset.
rpc RecordEvents(RecordEventsRequest) returns (RecordEventsResponse);
// Register the public key of an actor that may record events.
// Re-registering the same id with the same key is idempotent;
// with a different key it is refused.
rpc RegisterSigningKey(RegisterSigningKeyRequest) returns (SigningKeyList);
// Every registered signing key, revoked ones included, plus the
// hub's own service key.
rpc ListSigningKeys(google.protobuf.Empty) returns (SigningKeyList);
// Mark a signing key invalid from now on. The key keeps its row
// so signatures it already made stay checkable.
rpc RevokeSigningKey(RevokeSigningKeyRequest) returns (SigningKeyList);
// Sign the current chain head with the hub's service key and,
// when a timestamp authority is configured, have that signature
// timestamped per RFC 3161. Without an anchor a truncated tail
// is indistinguishable from a log that never grew.
rpc AnchorEventChain(AnchorEventChainRequest) returns (AnchorEventChainResponse);
// Build the evidence package for an auditor: the chain, the
// actor signatures, the public keys, the anchors and a verifier
// that runs without this hub. Returns the package bytes; the CLI
// writes them to a file.
rpc ExportEvidence(ExportEvidenceRequest) returns (ExportEvidenceResponse);
// Read the operator's `default_scope:` (the ordered list of
// provider segments the bare-form capability resolver tries
// when a flow names a capability without `<provider>/`
// prefix). Always returns the current in-memory copy.
rpc GetDefaultScope(google.protobuf.Empty) returns (DefaultScopeResponse);
// Replace the operator's `default_scope:`. The hub validates
// each entry against the namespace catalog before writing to
// disk. Returns the resulting snapshot so the client can
// refresh its UI in one round-trip.
rpc SetDefaultScope(SetDefaultScopeRequest) returns (DefaultScopeResponse);
// Re-read `auth.tokens:` from operator config + env vars and
// atomically swap the live token store. Used by operators to
// rotate tokens without restarting the daemon. Returns the
// new token count. Errors if the new config is invalid (env
// var missing, duplicate secret, no scopes, …) — the
// existing store stays in place so a botched rotation can't
// lock the operator out.
rpc ReloadAuth(google.protobuf.Empty) returns (ReloadAuthResponse);
// Read-only snapshot of the authentication policy as persisted
// in the operator config, for operator surfaces (Studio
// Settings → Security). Never carries secret material: token
// entries expose the env-var NAME and whether that variable is
// currently set — never the value; the jwt-rs256 validator
// exposes its key SOURCE (inline / file path), never the key.
// Admin-scoped like ReloadAuth.
rpc AuthStatus(google.protobuf.Empty) returns (AuthStatusResponse);
// Assemble the guided-setup plan for the given answers — a pure
// computation (chain_core::guided_setup::assemble), no state
// change, nothing written. Lets a GUI render the setup preview
// over its existing hub connection instead of spawning the CLI:
// on macOS that subprocess can be the app's first file-system
// touch and trigger a permission prompt BEFORE the operator has
// seen what would be set up — the wrong order for trust. Apply
// remains a deliberate separate step.
rpc PlanSetup(PlanSetupRequest) returns (PlanSetupResponse);
// List host services declared in the operator config. Each
// entry carries name + endpoint; reachability is operator-side
// (on-demand `chain service status` or Studio probe).
rpc ListServices(google.protobuf.Empty) returns (ServiceList);
// Declare a new host service in the operator config. Fails with
// ALREADY_EXISTS when a service of that name is configured.
rpc DeclareService(DeclareServiceRequest) returns (DeclareServiceResponse);
// Compare the running hub's version against the channel release
// manifest. Surfaced by the CLI as `chain update check` and by
// Studio's Doctor page as a "v0.x.y available" pill. Network
// failures are returned as `manifest_reachable=false` rather
// than gRPC errors so Studio can render gracefully when the
// release host is unreachable (air-gapped, offline laptop).
rpc CheckUpdate(google.protobuf.Empty) returns (CheckUpdateResponse);
// Active channel + per-channel daemon status. Lets Studio's
// settings page render which channel is current and whether
// each daemon is up. Mirrors the CLI's `fai daemon status`.
rpc ChannelStatus(google.protobuf.Empty) returns (ChannelStatusResponse);
// Filesystem locations the daemon owns: log file, db file,
// modules dir, flows dir, config file. Studio's Doctor page
// surfaces these so operators on Windows (who never touch
// a shell) can open them via the OS file manager.
rpc DaemonPaths(google.protobuf.Empty) returns (DaemonPathsResponse);
// Configured MCP servers + their last-discovery report.
// Studio's MCP-clients editor renders the result. Mirrors
// `chain mcp list` on the CLI.
rpc ListMcpClients(google.protobuf.Empty) returns (ListMcpClientsResponse);
// Re-run discovery against every configured MCP server and
// update the *live* store-index in place. Synthetic entries
// for tools the server no longer exposes are dropped.
// Mirrors `chain mcp refresh` but operates on the running
// daemon — Studio doesn't need to ask the operator to
// restart anything.
rpc RefreshMcpClients(google.protobuf.Empty) returns (ListMcpClientsResponse);
// Persist a new MCP server in `~/.chain/config.yaml` and
// re-run discovery. Returns the resulting list (same shape
// as ListMcpClients) so Studio can repaint in one round-trip.
rpc AddMcpClient(McpClientConfigEntry) returns (ListMcpClientsResponse);
// Remove an MCP server by name and re-run discovery so its
// synthetic capabilities disappear from the store.
rpc RemoveMcpClient(RemoveMcpClientRequest) returns (ListMcpClientsResponse);
// n8n bridges. Same shape as the MCP client RPCs above —
// every active workflow surfaces as `n8n.<name>.<slug>`.
rpc ListN8nEndpoints(google.protobuf.Empty) returns (ListN8nEndpointsResponse);
rpc RefreshN8nEndpoints(google.protobuf.Empty) returns (ListN8nEndpointsResponse);
rpc AddN8nEndpoint(N8nEndpointConfigEntry) returns (ListN8nEndpointsResponse);
rpc RemoveN8nEndpoint(RemoveN8nEndpointRequest) returns (ListN8nEndpointsResponse);
// Read-only system-AI status. Lets Studio render the
// "configure in Settings" affordance when the feature is
// off, and the privacy-mode badge when it is on.
rpc SystemAiStatus(google.protobuf.Empty) returns (SystemAiStatusResponse);
// Ask the system AI a one-shot question. Errors carry the
// failure category (disabled / env-missing / http / parse)
// so Studio can map them to the inline-fix-hint copy from
// `docs/architecture/system-ai.md`.
rpc AskAi(AskAiRequest) returns (AskAiResponse);
// Persist a new system-AI configuration. Updates the live
// hub state AND writes back to ~/.chain/config.yaml so the
// change survives daemon restart. Used by Studio's settings
// editor. Returns the resulting status (same shape as
// SystemAiStatus) so the UI can refresh in one round-trip.
rpc UpdateSystemAi(UpdateSystemAiRequest) returns (SystemAiStatusResponse);
// Probe a system-AI configuration with a tiny ping. The
// request body carries the *draft* config the operator is
// editing — Test Connection works *before* Save so the user
// doesn't have to commit a broken config to validate it.
// An all-empty body falls back to the live in-memory config.
rpc TestSystemAi(TestSystemAiRequest) returns (AskAiResponse);
// List the models the configured provider exposes via
// `GET /v1/models`. Studio's editor populates the model
// dropdown from this. Same draft-vs-live semantics as
// TestSystemAi.
rpc ListSystemAiModels(TestSystemAiRequest) returns (ListSystemAiModelsResponse);
// Pull (download + install) an Ollama model via the native
// /api/pull endpoint. Synchronous, may take minutes for
// large models. Same error-kind taxonomy as AskAi.
rpc PullSystemAiModel(PullSystemAiModelRequest) returns (PullSystemAiModelResponse);
// Same pull, with live progress. A model pull moves gigabytes, so
// the unary form above leaves a person waiting minutes with nothing
// to look at. Emits Ollama's own status plus byte counts per layer,
// ending in the response.
rpc PullSystemAiModelStream(PullSystemAiModelRequest)
returns (stream PullProgressEvent);
// Drop every cached System-AI explanation. Surfaced in
// Studio's Settings so operators can force a clean slate
// without changing model/privacy mode (which also flushes).
rpc ClearSystemLlmCache(google.protobuf.Empty) returns (ClearSystemLlmCacheResponse);
// Drop a single cached entry by prompt — the same prompt
// Studio sent in AskAi. Used by the "Regenerate" button so
// the next AskAi call falls through to the live provider.
rpc ForgetCachedExplanation(AskAiRequest) returns (google.protobuf.Empty);
// Detected host hardware tier + summary line. Studio's
// System-AI editor uses this to mark models as "may be slow
// on your hardware" without requiring a benchmark.
rpc HardwareInfo(google.protobuf.Empty) returns (HardwareInfoResponse);
// Bundled curated model database (quality tier, parameter
// count, recommended-for tier, notes). Studio merges this
// with the live `/v1/models` listing for richer chips. The
// `last_reviewed` field tells the operator how stale the
// curation is.
rpc ListSystemAiCuratedModels(google.protobuf.Empty)
returns (ListSystemAiCuratedModelsResponse);
// Federation (primary side). Issue a single-use bootstrap
// token enrolling a named satellite (`chain admin satellites
// peer-add`), and list the satellites currently connected
// (`chain admin satellites list`).
rpc IssueBootstrapToken(IssueBootstrapTokenRequest)
returns (IssueBootstrapTokenResponse);
rpc ListSatellites(google.protobuf.Empty) returns (SatelliteList);
// Revoke a satellite by UUID (`chain admin satellites revoke`):
// drops any live connection and refuses future connects even
// with a still-valid cert. Persisted across restarts.
rpc RevokeSatellite(RevokeSatelliteRequest) returns (google.protobuf.Empty);
}
message RevokeSatelliteRequest {
// Immutable hub UUID of the satellite to revoke.
string hub_id = 1;
}
message SubmitRequest {
// The flow definition as raw YAML.
bytes flow_yaml = 1;
// Named input values for the flow.
map<string, Payload> inputs = 2;
// When true (added 1.1), Submit returns immediately with the
// invocation id and the flow keeps running in the background. Poll
// GetInvocationStatus / fetch GetInvocationResult, or follow it live
// via SubmitStream. Only detached invocations are retained; unary
// detach=false is unchanged (synchronous, stateless).
bool detach = 3;
// Project slug this run belongs to (added phase 2). Overrides the
// flow YAML's `project:`; empty → the flow's project, then
// `general`. Every audit event, approval and detached row from this
// run is stamped (and hashed) with it. Grouping/filtering only —
// not tenancy.
string project = 4;
// Caller's key for "this is the same request as before" (added
// in hub 0.25). A second submit carrying a key the hub has already seen
// returns the first run instead of starting a second one, which is
// what a payment webhook that retries needs. At most 128 printable
// ASCII characters; empty means no deduplication. Scoped to the
// project.
string idempotency_key = 5;
}
message SubmitResponse {
InvocationId invocation_id = 1;
// Named output values produced by the flow.
map<string, Payload> outputs = 2;
}
// One event in a SubmitStream (added 1.1). Exactly one field is set.
message SubmitStreamEvent {
oneof event {
StepStarted step_started = 1;
StepFinished step_finished = 2;
ModuleEvent module_event = 3;
// Terminal success — identical to the unary SubmitResponse.
SubmitResponse final_result = 4;
// Terminal failure — the flow (or a step) errored.
StreamError error = 5;
}
}
message StepStarted {
string step = 1;
// Capability the step resolved to, e.g. "text.extract".
string capability = 2;
}
message StepFinished {
string step = 1;
bool ok = 2;
int64 duration_ms = 3;
}
// An ephemeral event a module emitted via host.emit-event (WIT 1.1).
// Never written to the audit log.
message ModuleEvent {
// The step whose module emitted this.
string step = 1;
// Module-defined label, e.g. "progress" / "token".
string name = 2;
// Event body.
Payload payload = 3;
}
message StreamError {
string message = 1;
// Machine-readable error class, the same vocabulary as the
// `chain-error-kind` trailer of a unary error (added in hub 0.25):
// flow_rejected, step_failed, step_timeout, approval_rejected,
// approval_timeout, unavailable, overloaded, precondition,
// not_found, conflict, internal. Empty from a hub older than 0.25.
string kind = 2;
}
// Lifecycle of a detached invocation (added 1.1).
message InvocationStatus {
enum Phase {
PHASE_UNKNOWN = 0;
PENDING = 1;
RUNNING = 2;
SUCCEEDED = 3;
FAILED = 4;
CANCELLED = 5;
// The hub went down while this run was executing (added in hub
// 0.25). The run did not finish and did not fail on its own; a
// caller that owns the work decides whether to submit it again.
INTERRUPTED = 6;
}
Phase phase = 1;
// Step currently executing (RUNNING), empty otherwise.
string current_step = 2;
// RFC 3339 timestamps; finished_at empty until the flow ends.
string started_at = 3;
string finished_at = 4;
// Error message when phase == FAILED, empty otherwise.
string error = 5;
}
message CancelInvocationResponse {
// True if a running invocation was signalled to cancel; false if it
// was already finished or unknown.
bool cancelled = 1;
}
// One row in the detached-runs monitor list.
message InvocationEntry {
string invocation_id = 1;
InvocationStatus status = 2;
// Flow name this invocation is running, empty when unknown.
string flow_name = 3;
// Project slug the run was stamped with (`general` when none).
string project = 4;
}
message InvocationList {
// Tracked detached invocations, newest-first by start time.
repeated InvocationEntry invocations = 1;
// Whether the operator enabled detached invocations
// (`detached.enabled`). Lets monitor UIs distinguish "feature
// off" from "on, but no runs yet" instead of guessing (added
// additively; absent = false on pre-1.1 hubs).
bool detached_enabled = 2;
}
message ModuleList {
repeated ModuleSummary modules = 1;
}
message ModuleSummary {
string name = 1;
string version = 2;
repeated CapabilityRef provides = 3;
}
message HealthStatus {
enum State {
UNKNOWN = 0;
SERVING = 1;
NOT_SERVING = 2;
}
State state = 1;
string detail = 2;
}
// HubAdmin messages
message CapabilityList {
repeated CapabilityEntry capabilities = 1;
}
message CapabilityEntry {
// Full capability identifier, e.g. "text.extract".
string capability = 1;
// Capability version (semver).
string version = 2;
// Module providing this capability.
string module_name = 3;
// Module's own version.
string module_version = 4;
// Where this capability comes from. Studio gates install
// affordances on this — only "wasm" caps have a bundle to
// install. Empty string is treated as "wasm" for
// backwards-compat with older hubs.
// "wasm" — declared by an installed WASM module
// "builtin" — implemented in the hub itself
// (e.g. system.approval)
// "federated" — discovered from an external MCP/n8n server;
// not installable via the module-store path
string kind = 5;
// Publisher identity (provider segment) of the capability.
// Always set on registered capabilities. "fai" for legacy
// bundles that didn't declare a provider. For federated
// capabilities, this is the operator's service `name:`
// (e.g. "deepwiki", "bmds.spark"). Wire-level addition for
// the naming convention; see
// `docs/reference/capability-namespaces.yaml`.
string provider = 6;
// Transport that delivers this capability to the Hub.
// Distinct from `kind` (which captures the install-vs-builtin
// distinction) — `source_kind` records HOW the Hub reaches
// the implementation. Studio renders this as a badge next to
// the capability name.
// "bundle" — installed .chain WASM bundle
// "system" — Hub built-in (fai.system/*)
// "mcp" — federated via an MCP service
// "n8n" — federated via an n8n endpoint
// "temporal" — federated via a Temporal service (e.g. SPARK)
// "webhook" — reserved for Phase 1+
string source_kind = 7;
// Whether the version on this capability is advisory rather
// than a hard contract. True for federated capabilities whose
// upstream service does not honour semver; operator pins are
// labels, not guarantees. Studio renders a warning badge.
bool version_advisory = 8;
}
message ModuleInfoRequest {
string module_name = 1;
}
message ModuleInfoResponse {
string name = 1;
string version = 2;
repeated CapabilityRef provides = 3;
// Permission strings exactly as declared in module.yaml.
repeated string permissions = 4;
// Filesystem location the module was loaded from.
string directory = 5;
// MIME allow-list for bytes-shaped inputs, copied verbatim
// from `module.yaml`'s `accepts_mime:` field. Empty means
// "no declared restriction". Studio uses this to pre-filter
// the OS file-picker so operators don't pick a file the
// module would reject.
repeated string accepts_mime = 6;
// Capabilities this module advisorily expects to be available,
// copied from module.yaml's optional `consumes:` list. Empty
// means "this is a leaf module with no declared dependencies".
// Studio surfaces "you'll also want these installed" hints
// based on this list; the hub does NOT enforce.
repeated ConsumedCapability consumes = 7;
// Declared inputs the module's invoke function accepts. The
// editor uses this to render per-field input ports with their
// canonical names + types and i18n tooltips. Empty when the
// manifest declares no inputs (rare; usually means the module
// is a pure data source).
repeated ModuleField inputs = 8;
// Declared outputs the module produces. The editor uses this
// to render one output port per declared field instead of
// collapsing every downstream reference into a single anchor.
repeated ModuleField outputs = 9;
}
message ConsumedCapability {
// Capability name, e.g. "llm.chat".
string capability = 1;
// Semver range constraint, e.g. "^0". Empty = any version.
string version = 2;
// Free-form rationale from the manifest's `why:` field.
string why = 3;
}
// One declared input or output field on a module. Carries the
// type descriptor (text / json / bytes / file) and a locale →
// description map for tooltips. The map is keyed by IETF locale
// tag ("en", "de", "ja", …) so callers pick their active
// locale with a single lookup + "en" fallback.
message ModuleField {
// Field name, e.g. "prompt" or "model_endpoint".
string name = 1;
// Type descriptor: one of text / json / bytes / file.
string type = 2;
// Locale → description. Empty map = no description declared
// (schema_version 1/2 manifests, or v3 manifests that left
// the field in shorthand form).
map<string, string> description = 3;
}
message CheckPermissionRequest {
string module_name = 1;
// Permission string in `<scope>: <value>` form.
string permission = 2;
}
message CheckPermissionResponse {
bool allowed = 1;
// Human-readable reason. Empty when allowed.
string reason = 2;
}
message EventLogRequest {
// Maximum number of events to return. Defaults to 100 when 0.
int32 limit = 1;
// Optional event_type filter; when empty, all types are returned.
repeated string event_types = 2;
// Optional project filter (slug). Empty = all projects. Scopes
// the audit view to one project — the per-project compliance
// export use case (`chain admin events --project`).
string project = 3;
}
message EventLogResponse {
repeated LoggedEvent events = 1;
}
message StreamEventsRequest {
// Backfill size before the stream switches to live updates.
// 0 means "no backfill, only new events". Defaults to 50 when
// unset; capped at 1000 server-side to bound the initial buffer.
int32 backfill = 1;
// Optional event_type filter; when empty, all types are streamed.
// The filter applies to both the backfill prefix and the live
// tail.
repeated string event_types = 2;
// Optional project filter (slug). Empty = all projects. Applies
// to both the backfill prefix and the live tail.
string project = 3;
}
message LoggedEvent {
string event_id = 1;
string timestamp = 2;
string event_type = 3;
string flow_execution = 4;
string invocation_id = 5;
string flow_name = 6;
string step_id = 7;
string module_name = 8;
string module_version = 9;
int64 duration_ms = 10;
string error = 11;
// Free-form JSON-string carrying event-type-specific fields:
// input/output sizes, model digest, sha256, etc. Empty when
// the event type has no structured detail. Studio renders
// this as a code block in the audit drill-down.
string detail = 12;
// Operator-friendly name of the token whose holder
// triggered this event. Empty when the call was anonymous
// (auth.tokens: not configured), when the event was emitted
// by hub-internal code (boot housekeeping, federation
// discovery), or when the row pre-dates the audit-
// attribution migration (0006).
string caller_name = 13;
// Project slug the run was stamped with (`general` when the
// run carried no explicit project). Bound into the V4 audit
// hash, so the attribution is tamper-evident. Empty on rows
// pre-dating the project migration (0008).
string project = 14;
}
message SaveFlowRequest {
// Flow name (used as the file name with .yaml extension).
string name = 1;
// Flow YAML content.
bytes flow_yaml = 2;
// If false and a flow with this name exists, return AlreadyExists.
bool overwrite = 3;
}
message SaveFlowResponse {
string name = 1;
bool created = 2;
}
message DeleteFlowRequest {
string name = 1;
}
message DeleteFlowResponse {
string name = 1;
}
message FlowList {
repeated FlowSummary flows = 1;
}
message FlowSummary {
string name = 1;
// Path on disk relative to the saved-flows directory.
string path = 2;
// Bytes on disk.
int64 size_bytes = 3;
// Verbatim `use:` strings of every step in the flow,
// deduplicated and sorted. Lets a GUI client decide whether
// a flow is currently runnable (every entry resolves to an
// installed module) without parsing the YAML itself.
repeated string required_capabilities = 4;
// The flow's own top-level `project:` slug; empty when the
// YAML has none (a run then lands in the caller's project,
// then `general`). The file wins on mismatch — same semantics
// as the CLI (docs/architecture/projects.md).
string project = 5;
// True when the file still carries the bundled-sample header —
// it arrived via the hub's sample import, not from an operator.
// Clients mark and group these so examples are never mistaken
// for real work. Deleting the header claims the flow.
bool sample = 6;
}
// One registered project (shared-hub registry row). Sealed
// projects never appear here — they are their own hub instance.
message ProjectInfo {
// Stable lowercase-kebab identifier stamped onto every run.
string slug = 1;
// Human display name (renamable without touching history).
string name = 2;
// Accent colour (hex, e.g. "#8b7cf6") for UI marking. Empty
// when unset.
string color = 3;
// Free-form description. Empty when unset.
string description = 4;
// Protection level: "open" (pure label) or "protected"
// (logically separated — no hard process barrier; the honest
// wording every UI must keep).
string isolation = 5;
// ISO-8601 UTC creation timestamp.
string created_at = 6;
}
message ProjectList {
// All registered projects, `general` first, then by display
// name (case-insensitive).
repeated ProjectInfo projects = 1;
}
message RunSavedFlowRequest {
string name = 1;
map<string, Payload> inputs = 2;
// Project slug override (added phase 2); empty → the saved flow's
// own `project:`, then `general`.
string project = 3;
}
message GetFlowDefinitionRequest {
string name = 1;
}
// Parsed shape of a saved flow. Currently surfaces only the
// declared inputs — that is what Studio needs to render its
// run-flow form. Fields can grow (steps, outputs) without
// breaking older clients.
message FlowDefinition {
string name = 1;
// Declared input keys plus their declared type tag, exactly
// as the flow YAML's `inputs:` section spelled them. Common
// values: "text", "bytes", "json", "file".
repeated FlowInputSpec inputs = 2;
}
message FlowInputSpec {
// Input key (the name the flow YAML uses).
string name = 1;
// Declared type tag from the flow YAML — opaque string so
// the wire stays stable as the type system grows.
string type = 2;
}
message SearchStoreRequest {
// Free-text search; matches name, tagline, description, category, tags.
string query = 1;
// Optional category filter.
string category = 2;
// Optional tag filter.
string tag = 3;
// Optional status filter: "published", "alpha", or "planned".
string status = 4;
// Maximum results; defaults to 50 when 0.
int32 limit = 5;
// Exact-match provider segment filter (0.12+). Empty string
// matches any provider.
string provider = 6;
// First-dotted-segment-of-name filter (0.12+). E.g. "text"
// matches text.extract, text.summarize, … but not
// image.classify. Empty matches any namespace.
string namespace = 7;
}
message StoreSearchResponse {
repeated StoreEntry entries = 1;
}
message InstallModuleRequest {
// Local path or http(s) URL of the .chain bundle, OR a
// capability name (e.g. "text.extract") resolved via the
// store index.
string source = 1;
// Optional expected SHA-256 hex string for verification.
string expected_sha256 = 2;
// Optional explicit version when `source` is a capability
// name. Ignored for URL / local-path sources (the bundle's
// own manifest dictates the version). Empty string falls
// back to "highest-priority version from the store index".
string version = 3;
}
message InstallModuleResponse {
string name = 1;
string version = 2;
// Number of capabilities the installed module provides.
int32 capability_count = 3;
}
// One message in an InstallModuleStream.
message InstallProgressEvent {
oneof event {
// Progress moved, or a phase started or finished.
InstallProgressUpdate update = 1;
// The install succeeded; always the final message.
InstallModuleResponse finished = 2;
// The install failed; always the final message. Carries the same
// text the unary call would have returned as its status message.
string failed = 3;
}
}
// A single progress observation.
message InstallProgressUpdate {
// Stable phase identifier: "resolve", "download" or "install".
// Clients map it to their own wording; it is not display text.
string phase = 1;
// English fallback label for the phase ("Downloading"). Clients with
// their own translations key off `phase` and ignore this.
string stage = 2;
// Overall progress across all phases, 0..100, monotonic. Absent
// means the extent is not knowable yet — show an indeterminate
// indicator, never a bar parked at zero.
optional float percent = 3;
// Bytes received so far during the download phase.
uint64 bytes_received = 4;
// Total bytes the server announced. Zero means the server sent no
// content-length, so only `bytes_received` is meaningful.
uint64 bytes_total = 5;
// The named phase just finished.
bool phase_done = 6;
}
message UninstallModuleRequest {
// Module name as the registry knows it. Empty → InvalidArgument.
string name = 1;
// Optional exact version to remove when multiple versions of the
// same `(provider, name)` are installed side-by-side. Empty
// falls back to "remove the highest-version match".
string version = 2;
}
message UninstallModuleResponse {
string name = 1;
// Version that was removed; "unknown" when the manifest was
// unreadable for some reason but the directory still got wiped.
string version = 2;
}
message FetchModuleDocsRequest {
// Module name as the store-index knows it. The hub looks up
// its repository URL and tries the well-known raw-README
// paths (Forgejo / GitHub / GitLab style), then any
// `docs_url` override the module declares.
string name = 1;
// Preferred locale code (e.g. "de", "en"). When set, the hub
// first tries `README.<locale>.md` before falling back to the
// generic `README.md`. Empty string = no locale preference.
string locale = 2;
}
message FetchModuleDocsResponse {
// Empty on success; otherwise one of:
// "not_found" — module not in the store-index
// "no_docs" — index has no repository or docs URL
// "network" — http error / unreachable
// "auth" — registry returned 401/403
// "parse" — body was not utf-8
string error_kind = 1;
// Human-readable detail. On success this is the markdown
// content; on failure a fix hint.
string text = 2;
// The URL the hub fetched from, so Studio can render a
// "View on <host>" link for context.
string source_url = 3;
}
message GetInstalledModuleDocsRequest {
// Capability id (e.g. `text.extract`) or module-manifest name
// (e.g. `text-extract`). The hub maps capability → module via
// the registry; falls back to treating the name as a
// directory name.
string name = 1;
// Preferred locale code (e.g. "de", "en"). When set and not
// "en", `MODULE.<locale>.md` is tried first; otherwise the
// generic `MODULE.md` is used. Empty string = no preference.
string locale = 2;
}
message GetInstalledModuleDocsResponse {
// Markdown body. Empty when the module is installed but ships
// no inline docs — Studio uses this to hide its docs button.
string text = 1;
// Absolute path on the hub host that the body was read from,
// for "loaded from /path/MODULE.md" hints in Studio. Empty
// when text is empty.
string source_path = 2;
// True when the module wasn't installed at all. Distinct from
// "installed but no inline docs" so Studio can show different
// affordances ("install first" vs "no inline docs available").
bool not_installed = 3;
}
message InvokePluginThemeRequest {
// Capability name the operator asked for, e.g.
// `studio.theme.solarized`. The hub maps this to the
// installed plugin directory.
string capability = 1;
// "light" or "dark" — the plugin returns a ColorScheme
// for this brightness. Plugins that don't recognise the
// value return PluginError::declined and the hub
// surfaces that as a friendly error.
string brightness = 2;
}
message InvokePluginTranslateRequest {
// Capability name (e.g. `studio.translate.ollama`).
string capability = 1;
// Text to translate. UTF-8, arbitrary length the plugin
// tolerates.
string text = 2;
// BCP-47 source locale. Empty = let the plugin auto-detect.
string from_locale = 3;
// BCP-47 target locale. Required; the host always knows it.
string to_locale = 4;
}
message InvokePluginTranslateResponse {
// Translated text. Returns verbatim what the plugin
// emits — no normalisation by the hub.
string translated = 1;
}
message InvokePluginThemeResponse {
// Echo of the brightness input. Plugins are expected to
// round-trip it; if they don't the client treats that as
// a contract violation.
string brightness = 1;
// 14 ARGB tokens in Material 3 order:
// primary, on_primary, secondary, on_secondary,
// tertiary, on_tertiary, error, on_error,
// surface, on_surface, surface_variant,
// on_surface_variant, outline, outline_variant.
// Studio merges any missing slot (well-behaved plugins
// send all 14) with its built-in fallback before
// applying the scheme.
repeated uint32 tokens = 2;
}
message ListApprovalsRequest {
// Filter by status. Empty = all. Allowed wire values:
// "pending", "approved", "rejected", "expired".
repeated string statuses = 1;
// Maximum rows; defaults to 100 when 0.
int32 limit = 2;
// Optional project filter (slug). Empty = all projects.
string project = 3;
}
message ApprovalList {
repeated PendingApprovalEntry entries = 1;
}
message PendingApprovalEntry {
string approval_id = 1;
string flow_execution = 2;
string flow_name = 3;
string step_id = 4;
string prompt = 5;
// Truncated string preview of the payload the flow handed to
// the approval step, for reviewer context.
string payload_preview = 6;
string created_at = 7;
// Empty when the approval has no timeout.
string expires_at = 8;
// One of "pending", "approved", "rejected", "expired".
string status = 9;
// Empty until decided.
string decided_at = 10;
string decided_by = 11;
string reason = 12;
// Project slug the requesting run was stamped with
// (`general` when the run carried no explicit project).
string project = 13;
}
message DecideApprovalRequest {
string approval_id = 1;
enum Decision {
DECISION_UNSPECIFIED = 0;
APPROVE = 1;
REJECT = 2;
}
Decision decision = 2;
// Reviewer attribution, recorded in the audit trail. Required.
string reviewer = 3;
// Free-form reason. Required for REJECT, ignored for APPROVE.
string reason = 4;
}
message DecideApprovalResponse {
string approval_id = 1;
// The new status: "approved" or "rejected".
string status = 2;
}
message VerifyEventChainResponse {
// Total events scanned.
int64 total = 1;
// Number of events verified before any tamper detection.
// Equal to total on a clean chain.
int64 verified = 2;
// Empty when no tampering was detected; otherwise the
// event_id of the first inconsistent row.
string tampered_at = 3;
}
message ServiceList {
repeated DeclaredService services = 1;
}
// Declare a host service in the operator config (`services:`).
// The hub persists it to ~/.chain/config.yaml with the same
// round-trip semantics as the MCP/n8n writers (every other key
// stays intact). Services are read at daemon start, so the
// response says honestly that a restart is required.
message DeclareServiceRequest {
string name = 1;
string endpoint = 2;
// Empty defaults to "/".
string health_path = 3;
repeated string tags = 4;
}
message DeclareServiceResponse {
// True until the hub learns to hot-reload `services:` — the
// caller should surface "takes effect after a daemon restart".
bool restart_required = 1;
}
message DeclaredService {
string name = 1;
string endpoint = 2;
// Empty defaults to "/".
string health_path = 3;
repeated string tags = 4;
// Network reach of `endpoint`, classified from its host part
// (no DNS lookups — named hosts other than localhost report
// "unknown"):
// "loopback" — 127.0.0.0/8, ::1, localhost
// "private" — RFC1918 / ULA / link-local ranges
// "public" — any other literal IP
// "unknown" — unparseable, or a hostname we cannot judge
// Empty from pre-0.23 hubs.
string exposure = 5;
}
message StoreEntry {
string name = 1;
string tagline_en = 2;
string tagline_de = 3;
string description_en = 4;
string description_de = 5;
string category = 6;
repeated string tags = 7;
repeated string requires_capabilities = 8;
repeated string requires_services = 9;
string license = 10;
string repository = 11;
string best_version = 12;
// Status of best_version: "published", "alpha", "planned", or empty.
string status = 13;
bool installed = 14;
// True iff the store-index marks this module as editorially
// featured. Studio renders featured entries in a separate
// strip above the main grid. Curated quarterly in the hub's
// bundled seed.yaml — same review cadence as the curated
// model database.
bool featured = 15;
// Optional URL of a square icon (PNG / SVG, 256px+).
// Studio loads and renders this in the detail sheet's hero
// header in place of the category-derived fallback. Empty
// → fall back to the category icon.
string icon_url = 16;
// Optional screenshot URLs in display order. Studio renders
// them as a horizontally-scrollable strip in the detail
// sheet so operators can see what the module *does* before
// installing.
repeated string screenshot_urls = 17;
// Explicit docs URL override. Empty → hub falls back to the
// well-known raw-README paths against `repository`.
// Use this when the README lives at a non-default branch /
// path or when the docs are a separate Markdown file.
string docs_url = 18;
// Origin of this entry. "native" (downloadable bundle, the
// default for every seed.yaml entry) or "federated" (routes
// through a bridge — MCP, n8n, …). Studio uses the value to
// branch the install action.
string kind = 19;
// Provider id for federated entries. Empty for native.
// For MCP this is the operator's `mcp_clients[].name`.
// Studio renders "via mcp:<provider>" so the operator sees
// where a synthetic capability comes from.
string provider = 20;
// Transport delivering this entry's capability. Distinct
// from `kind` (native-vs-federated) — `source_kind` says
// HOW the Hub reaches the implementation. Values mirror
// `CapabilityEntry.source_kind`:
// "bundle" — installed .chain WASM bundle (native entries)
// "mcp" — federated via an MCP service
// "n8n" — federated via an n8n endpoint
// "temporal" — federated via a Temporal service (e.g. SPARK)
// "webhook" — reserved for Phase 1+
// Empty string falls back to deriving from `kind` for
// pre-0.12 hubs.
string source_kind = 21;
// Name of the store this entry was loaded from: "bundled" for the
// built-in seed, otherwise the operator-added store's name. Distinct
// from source_kind (the transport) — this is the ORIGIN store. Studio
// groups modules by it and shows a "from <store>" label.
string source = 22;
// Canonical, normalized category slug (e.g. "data", "text-language",
// "studio-themes"). The hub maps the free-form `category` onto a
// fixed taxonomy by capability namespace, so different stores using
// different labels ("data" vs "data-processing") land in ONE bucket.
// Studio groups + filters by this, not the raw `category`. Empty
// from pre-0.21 hubs → Studio falls back to `category`.
string canonical_category = 23;
// Human-readable label for `canonical_category` (e.g. "Data &
// Formats"). English; Studio may localize via the slug.
string canonical_category_label = 24;
// How an install of this entry would be verified, given its
// origin store and the operator's CURRENT security policy. The
// hub computes this with the same resolution the install path
// enforces (pinned store key -> trusted publishers -> policy),
// so the display can never disagree with the gate:
// "pinned-key" — verified against the origin store's
// pinned cosign key (or the built-in
// official key for bundled/official)
// "trusted-publishers" — verified against the applicable
// trusted-publisher list
// "unverified" — require_signatures is off; installs
// are NOT signature-checked
// "blocked" — policy requires signatures but no key
// material applies to this source; an
// install would be refused
// "federated" — bridge entry (MCP/n8n/…); no bundle
// signature applies
// Empty from pre-0.23 hubs — clients keep their generic note.
string install_verification = 25;
// Maintainer display strings from the store index (one per
// person/organization). Empty when the index does not specify
// any — clients render an honest "not specified".
repeated string maintainers = 26;
// Where the module's data comes from, for `source.*` capabilities.
// Absent for every other module: a text splitter reaches no
// third-party material and has no provenance to declare.
optional DataSource data_source = 27;
}
// Provenance of the material a `source.*` module fetches.
//
// Separate from the module's own licence, which covers its code. A
// module can be Apache-2.0 while the corpus it reaches is
// public-domain statute, CC-BY, or licence-gated. Clients show this
// before the install button so an operator sees the terms they are
// taking on.
message DataSource {
// Publisher, as a person would name it.
string name = 1;
// Canonical URL of the upstream source.
string url = 2;
// Terms in plain words, not SPDX: the material often carries no
// software licence at all.
string license = 3;
// Attribution the operator must carry with the output. Empty when
// the upstream requires none.
string attribution = 4;
// True when a copy of the data ships inside the module bundle.
// Forbidden for `source.*` modules, allowed elsewhere only when
// `redistribution` says the publisher permits it, so a client can
// show the operator which of the two they are installing.
bool bundled = 5;
// What the publisher's terms say about passing the data on:
// `allowed`, `forbidden`, `unclear`, or empty when the question
// does not arise (nothing is bundled).
string redistribution = 6;
}
message ChannelStatusResponse {
// Active channel pointer from `~/.chain/current-channel`.
string active = 1;
repeated ChannelEntry channels = 2;
}
message ChannelEntry {
string name = 1;
uint32 port = 2;
// True iff a daemon is currently bound to that channel's port
// (PID file present + process alive).
bool running = 3;
// Endpoint string from `~/.chain/run/<channel>.endpoint` when
// the daemon is up, otherwise empty.
string endpoint = 4;
}
message DaemonPathsResponse {
// Channel-scoped log file path (empty if Studio cannot
// resolve one — e.g. older daemon writes only to stderr).
string log_path = 1;
// SQLite audit-log database path.
string db_path = 2;
// Modules directory the registry scans.
string modules_dir = 3;
// Saved flows directory.
string flows_dir = 4;
// Operator config file (~/.chain/config.yaml).
string config_path = 5;
// PID file the daemon supervisor writes (for the active
// channel).
string pid_path = 6;
}
message CheckUpdateResponse {
// The active channel ("dev", "beta", "production").
string channel = 1;
// The version the running hub was built with.
string local_version = 2;
// The version the manifest advertises as latest. Empty if
// `manifest_reachable` is false.
string latest_version = 3;
// True iff `latest_version > local_version` (semver-aware).
bool update_available = 4;
// RFC 3339 timestamp of the release. Empty if not present.
string released_at = 5;
// URL of the release notes for `latest_version`. Empty if not
// present in the manifest.
string release_notes_url = 6;
// True iff the release host responded with a parseable manifest.
// False on network errors / 404 / malformed JSON. The remaining
// string fields are empty in that case; `reason` carries a
// human-readable diagnostic.
bool manifest_reachable = 7;
// Empty on success; carries an error description when
// `manifest_reachable=false`.
string reason = 8;
// Manifest URL that was queried (configurable per operator).
string manifest_url = 9;
}
message SystemAiStatusResponse {
// True iff `system_llm` is configured AND privacy_mode != off.
bool enabled = 1;
// openai / anthropic / "" — empty when disabled.
string provider = 2;
// The endpoint URL the operator configured. Empty when disabled.
string endpoint = 3;
// Model identifier. Empty when disabled.
string model = 4;
// off / redacted / full — never empty.
string privacy_mode = 5;
// Name of the env var holding the API key (empty = no auth).
// Studio's settings page renders the *name*; never the value.
string api_key_env = 6;
// Number of cached System-AI explanations currently stored.
// Surfaced in Doctor + Settings so operators see the cache
// earning its keep.
uint64 cache_count = 7;
}
message AskAiRequest {
// The prompt the operator wants answered. Studio assembles
// this client-side from the audit event being explained
// and the chosen privacy mode.
string prompt = 1;
// When true, skip the persistent cache and always hit the
// live provider. Studio's "Regenerate" button passes this so
// the operator can ask the model to think again.
bool force_fresh = 2;
}
message AskAiResponse {
// Failure category, mapped from `system_llm::SystemLlmError`.
// Empty on success. Studio surfaces each value with a fix hint.
// Values: "" (success), "disabled", "env_missing", "network",
// "http", "parse", "empty_response".
string error_kind = 1;
// Human-readable diagnostic / answer. Always populated:
// either the assistant text on success, or the error detail
// on failure.
string text = 2;
// Round-trip latency in milliseconds (success only). For
// cache hits this is the *original* generation latency, not
// the cache-lookup time — the UI renders it as "originally
// took X" so the operator sees what a live call would cost.
uint32 latency_ms = 3;
// True iff the answer came from the persistent cache rather
// than a fresh provider round-trip.
bool cached = 4;
// ISO-8601 timestamp the cached entry was first generated.
// Empty for fresh answers.
string cached_at = 5;
// How many times this entry has been served from cache.
// 0 for fresh answers.
uint32 cache_hits = 6;
}
message ClearSystemLlmCacheResponse {
// Number of cached entries that were dropped.
uint64 purged = 1;
}
message UpdateSystemAiRequest {
// ollama / openai / lmstudio / vllm / custom (defaults to
// ollama if empty).
string provider = 1;
// Full URL up to and including /v1. Empty + privacy_mode!=off
// → returns InvalidArgument.
string endpoint = 2;
// Model identifier the provider expects. Empty +
// privacy_mode!=off → returns InvalidArgument.
string model = 3;
// Name of the env var holding the API key. Empty = no auth.
string api_key_env = 4;
// off / redacted / full. Empty defaults to "off".
string privacy_mode = 5;
}
message TestSystemAiRequest {
// Draft system-AI config to probe with. Empty fields fall
// back to the live in-memory config — handy for "test current
// settings" without re-sending them.
string provider = 1;
string endpoint = 2;
string model = 3;
string api_key_env = 4;
string privacy_mode = 5;
}
message ListSystemAiModelsResponse {
// Empty on success. Otherwise: same error-kind taxonomy as
// AskAi (network / http / parse / disabled / env_missing).
string error_kind = 1;
string text = 2;
repeated SystemAiModel models = 3;
}
message SystemAiModel {
// Model identifier the operator passes as `model:`.
string id = 1;
// Optional family / owner string the provider returned.
string owned_by = 2;
}
message PullSystemAiModelRequest {
// Draft endpoint + auth. Required; the model is the operator's
// pick. Currently only Ollama-style /api/pull is supported.
string endpoint = 1;
string api_key_env = 2;
// Model id to pull, e.g. `gemma3:4b`, `llama3.2:3b`.
string model = 3;
}
message PullSystemAiModelResponse {
string error_kind = 1;
string text = 2;
// Total wall-clock time the pull took, in milliseconds.
uint32 elapsed_ms = 3;
}
// One message in a PullSystemAiModelStream.
message PullProgressEvent {
oneof event {
// The pull moved on.
PullProgressUpdate update = 1;
// Terminal message, success or failure (see its error_kind).
PullSystemAiModelResponse finished = 2;
}
}
// A single observation while a model downloads.
message PullProgressUpdate {
// The backend's own status text, e.g. "pulling manifest". Passed
// through verbatim rather than translated: it names layers and
// digests a client cannot reconstruct.
string status = 1;
// Bytes fetched so far for the layer this status refers to.
uint64 completed = 2;
// Size of that layer; zero for statuses that carry no size, which
// clients show as indeterminate rather than as zero progress.
uint64 total = 3;
}
message HardwareInfoResponse {
// tiny / small / balanced / large / unknown — see
// docs/architecture/system-ai.md → "Hardware tiers".
string tier = 1;
// CPU brand string, e.g. "Apple M3 Pro".
string cpu_brand = 2;
uint32 cpu_cores = 3;
uint64 ram_mb = 4;
bool apple_silicon = 5;
bool dedicated_gpu = 6;
// Human-readable summary the editor renders verbatim, e.g.
// "Apple M3 Pro · 16 GB · balanced".
string summary = 7;
}
message ListSystemAiCuratedModelsResponse {
repeated CuratedModel models = 1;
// ISO-date string from models.yaml (e.g. "2026-05-07"). Lets
// Studio show "curation last reviewed 3 weeks ago".
string last_reviewed = 2;
}
message CuratedModel {
string id = 1;
string family = 2;
// Parameter count in billions. 0 for closed-source cloud
// models where we don't publish a number.
float params_b = 3;
// basic / good / excellent.
string quality_tier = 4;
// tiny / small / balanced / large.
string min_hw_tier = 5;
// Context window in K tokens (8 = 8192).
uint32 context_k = 6;
// Free-form note rendered as a tooltip in Studio.
string notes = 7;
// Licence identifier (gemma-license, apache-2.0, …).
string license = 8;
}
message ClearEventLogRequest {
// Operator handle recorded in the chain.reset marker so the
// discontinuity is attributable. Required.
string reviewer = 1;
// Free-form reason recorded in the chain.reset marker. Required —
// dropping audit events without a reason is the kind of action
// operators are asked to defend later.
string reason = 2;
}
message ClearEventLogResponse {
// Number of events that were purged (excludes the new
// chain.reset marker that seeds the fresh chain).
uint64 purged = 1;
// Channel the operation ran on, echoed back so the CLI can
// confirm which environment was affected.
string channel = 2;
}
// One event that happened outside the hub.
message ExternalEvent {
// Type tag. Must start with one of the external prefixes
// (`ai.`, `human.`, `decision.`, `compliance.`, `ext.`); the hub
// writes its own history and a client cannot add to it.
string event_type = 1;
// Caller-chosen key, unique within the project. Required.
string idempotency_key = 2;
// When the event happened in the calling system (ISO 8601 with a
// zone), or empty. The hub always records its own receipt time.
string occurred_at = 3;
// The event's fields as a JSON object, submitted and stored
// verbatim: the signature is over exactly these bytes, so
// re-serializing them would break it. The decision event types
// require `case` plus their own fields.
string detail_json = 4;
// Key id the signature belongs to.
string key_id = 5;
// Base64 Ed25519 signature over the domain tag
// `CHAIN-EXTERNAL-EVENT-V1`, a NUL byte, and then project,
// event_type, idempotency_key, occurred_at and detail_json, each
// prefixed with its byte length as little-endian uint32.
string signature_b64 = 6;
}
message RecordEventsRequest {
// Project the events belong to. Empty means `general`.
string project = 1;
// The events, in the order they happened. An event may refer to
// another event of the same batch.
repeated ExternalEvent events = 2;
}
message RecordedExternalEvent {
// Event id in the chain.
string event_id = 1;
// SHA-256 of the signed payload.
string content_sha256 = 2;
// True when the idempotency key was already recorded: this is
// the first submission's event id, nothing was appended.
bool replayed = 3;
}
message RecordEventsResponse {
// One entry per submitted event, in request order.
repeated RecordedExternalEvent events = 1;
}
message SigningKeyEntry {
string key_id = 1;
// Project glob the key may record into; `*` for every project.
string project = 2;
// Pseudonym of the actor. An event naming an actor must be
// signed with that actor's key.
string actor = 3;
// `service` for a machine, otherwise the person's role.
string role = 4;
// Always `ed25519` today.
string algorithm = 5;
// Raw 32-byte public key, base64.
string public_key = 6;
string added_at = 7;
// Empty while the key is valid.
string revoked_at = 8;
}
message RegisterSigningKeyRequest {
SigningKeyEntry key = 1;
}
message RevokeSigningKeyRequest {
string key_id = 1;
}
message SigningKeyList {
repeated SigningKeyEntry keys = 1;
// The hub's own service key, base64. It signs the anchors.
string service_public_key = 2;
}
message AnchorEventChainRequest {
// Timestamp authority to use for this anchor. Empty takes the
// operator's `audit.timestamp_authority`; the anchor is written
// with a signature but without a timestamp when neither is set.
string timestamp_authority = 1;
}
message AnchorEventChainResponse {
string anchor_id = 1;
// Chain head the anchor covers.
string head_event_id = 2;
string head_sha256 = 3;
int64 event_count = 4;
// Base64 Ed25519 signature of the service key over the anchor
// payload.
string signature = 5;
// Authority that timestamped it, empty when none was configured.
string tsa_url = 6;
// The time the authority asserted, empty when none was used.
string tsa_time = 7;
}
message ExportEvidenceRequest {
// Project whose events are exported with their payload. Other
// projects' rows travel as hashes only, so the chain still
// verifies without disclosing their content. Empty exports every
// project in full.
string project = 1;
}
message ExportEvidenceResponse {
// The package as a gzipped tar archive.
bytes package = 1;
// File name the CLI suggests.
string filename = 2;
// Number of events in the package.
int64 event_count = 3;
}
message SetDefaultScopeRequest {
// New `default_scope` value. The first entry is the
// primary scope (the resolver consults the others in order
// when the primary doesn't match). At least one entry is
// required; the hub returns InvalidArgument otherwise.
repeated string scope = 1;
}
message DefaultScopeResponse {
// The current `default_scope` after the operation.
repeated string scope = 1;
// Catalog-known publisher segments the operator may pick
// from, sorted alphabetically. Surfaces a typeahead-friendly
// shortlist in the Studio editor; arbitrary entries are
// still allowed (operator may run a private publisher
// segment that isn't in the central catalog).
repeated string known_providers = 2;
}
message ReloadAuthResponse {
// Number of tokens loaded into the live store after the
// swap. Operators sanity-check this against the number
// they expected to have in `auth.tokens:`.
uint32 token_count = 1;
}
// Guided-setup answers, mirroring chain_core::guided_setup::
// SetupAnswers (kebab-case wire values, e.g. "trying-out").
// Unknown values are an INVALID_ARGUMENT — the enums live in Rust.
message PlanSetupRequest {
string scenario = 1;
string intent = 2;
string target = 3;
bool require_approval = 4;
bool data_must_stay_local = 5;
bool allow_unsigned_modules = 6;
}
// The assembled SetupPlan — field-for-field what `chain init
// --answers … --plan-json` prints, so a GUI can render the same
// preview from either source.
message PlanSetupResponse {
string profile = 1;
repeated string modules = 2;
string starter_flow = 3;
string runbook = 4;
repeated string curated_docs = 5;
bool require_signatures = 6;
bool worm_audit = 7;
bool approval_step = 8;
}
message AuthStatusResponse {
// Validator kind in the on-disk operator config: "static" or
// "jwt-rs256".
string validator = 1;
// True when the hub CURRENTLY accepts anonymous calls — computed
// from the live validator, not the on-disk config (the two differ
// until `ReloadAuth` picks up a config edit; see reload_required).
// Anonymous mode is the static validator with an empty
// `auth.tokens:` list — the local-dev default.
bool anonymous_allowed = 2;
// Static token entries; empty for the jwt-rs256 validator.
repeated AuthTokenInfo tokens = 3;
// jwt-rs256 parameters; unset for the static validator.
JwtValidatorInfo jwt = 4;
// True when the on-disk auth config (or the env vars it
// references) no longer produces the validator the hub is
// enforcing — the operator edited config.yaml or rotated a
// secret and still needs `ReloadAuth` (or a restart). Also true
// when the on-disk config is currently invalid.
bool reload_required = 5;
}
message AuthTokenInfo {
// Operator-friendly name as it appears in audit-log lines.
string name = 1;
// Name of the environment variable holding the secret. The
// value itself never crosses the wire.
string token_env = 2;
// Whether that environment variable is currently set in the
// daemon's environment — the common rotation footgun.
bool env_set = 3;
// Scope grants, verbatim from config (coarse scopes like
// `read`/`execute`/`admin` and fine-grained T5 patterns like
// `execute:llm.*`).
repeated string scopes = 4;
// Requests-per-minute quota; 0 = unlimited.
uint32 rate_limit_per_minute = 5;
}
message JwtValidatorInfo {
// Where the RSA public key comes from: "inline-pem" when the
// key is embedded in config, else the configured file path.
string key_source = 1;
// Required `aud` claim; empty = not checked.
string audience = 2;
// Required `iss` claim; empty = not checked.
string issuer = 3;
// Claim carrying the caller's scopes.
string scope_claim = 4;
}
message McpClientConfigEntry {
// Operator-friendly name. Becomes the second segment of
// every discovered capability id: `mcp.<name>.<tool>`.
// Must be unique and not contain dots.
string name = 1;
// Endpoint URL. HTTP(S) for streamable-HTTP servers,
// `stdio://<command>` for local stdio servers.
string endpoint = 2;
// Optional env-var name holding a bearer token.
string api_key_env = 3;
// Optional human-readable description.
string description = 4;
}
message ListMcpClientsResponse {
// Every configured server (regardless of last-discovery
// outcome).
repeated McpClientStatus clients = 1;
}
message McpClientStatus {
McpClientConfigEntry config = 1;
// Number of tools the last discovery pass returned. 0
// before discovery has run or on failure.
uint32 tool_count = 2;
// Empty on success; otherwise the error_kind taxonomy
// (`invalid_endpoint`, `not_implemented`, `network`,
// `http`, `server`, `parse`, `env_missing`).
string error_kind = 3;
// Human-readable diagnostic. On success "registered N
// tools"; on failure the error message.
string message = 4;
}
message RemoveMcpClientRequest {
string name = 1;
}
message N8nEndpointConfigEntry {
string name = 1;
// Base URL without the /api/v1 suffix.
string base_url = 2;
string api_key_env = 3;
string description = 4;
}
message ListN8nEndpointsResponse {
repeated N8nEndpointStatus endpoints = 1;
}
message N8nEndpointStatus {
N8nEndpointConfigEntry config = 1;
uint32 workflow_count = 2;
string error_kind = 3;
string message = 4;
}
message RemoveN8nEndpointRequest {
string name = 1;
}
message IssueBootstrapTokenRequest {
// Operator-friendly satellite display name the token enrols.
string satellite_name = 1;
// Optional region tag signed into the issued cert at enrollment.
string region = 2;
// Token lifetime in seconds; 0 defaults to 24h server-side.
uint64 ttl_seconds = 3;
}
message IssueBootstrapTokenResponse {
// The single-use token. Shown once; hand it to the satellite
// operator over a secure channel.
string token = 1;
// ISO-8601 expiry of the token.
string expires_at = 2;
// The primary's CA certificate PEM. The operator installs this on
// the satellite (`federation.primary_ca`) alongside the token so
// the satellite verifies the primary on its very first connect —
// closing the first-connect MITM window with no extra lookup.
string primary_ca_pem = 3;
}
message SatelliteList {
repeated SatelliteEntry satellites = 1;
}
message SatelliteEntry {
// Immutable hub UUID of the satellite.
string hub_id = 1;
// Operator-chosen display name.
string display_name = 2;
// Ch∆In version the satellite reported.
string hub_version = 3;
// Negotiated federation wire version.
uint32 wire_version = 4;
// Region tag, empty when none.
string region = 5;
// Capability ids the satellite currently advertises.
repeated string capabilities = 6;
}
// ---- Store management (Studio store manager) ----
message ListStoresRequest {}
message StoreSource {
// "bundled" for the seed index, else the operator-given name.
string name = 1;
// Index URL; empty for the bundled seed.
string url = 2;
// False for the bundled seed (cannot be removed).
bool removable = 3;
// Modules currently contributed by this source to the live index.
int32 module_count = 4;
// True when this store pins a cosign publisher key
// (`trust.public_key_pem`, or the built-in official key for the
// bundled seed) — installs from it are verified against that key
// whenever signature checking is on.
bool key_pinned = 5;
}
message ListStoresResponse {
repeated StoreSource stores = 1;
// Operator policy snapshot so store UIs can say honestly whether
// installs are signature-checked at all.
bool require_signatures = 2;
// Number of globally trusted publisher identities
// (`security.trusted_publishers`).
int32 trusted_publisher_count = 3;
}
message AddStoreRequest {
// Operator-friendly name, unique within configured stores.
string name = 1;
// Index URL: https:// , http:// , or file:// .
string url = 2;
// Optional bearer-token env var name (hub reads $value at request time).
string bearer_env = 3;
// Optional HTTP Basic username.
string basic_user = 4;
// Optional HTTP Basic password env var name. Pair with basic_user.
string basic_password_env = 5;
// Optional PEM PUBLIC key to pin for this store (cosign key-pinning).
// When set, signed modules from this store verify against THIS
// publisher key instead of the global/built-in vendor anchor, so a
// domain publisher signs with its own key without the vendor master.
string pinned_pubkey_pem = 6;
}
message AddStoreResponse {
// Modules the new store contributed to the live index.
int32 modules_added = 1;
// Human-readable result (e.g. "added 8 modules from reclaim").
string message = 2;
}
message RemoveStoreRequest {
string name = 1;
}
message RemoveStoreResponse {
bool removed = 1;
string message = 2;
}