1914 lines
71 KiB
Protocol Buffer
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;
|
|
}
|