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 // /flows/.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..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:`); `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 `/` // 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..`. 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 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 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 description = 3; } message CheckPermissionRequest { string module_name = 1; // Permission string in `: ` 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 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..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 " 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..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:" 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 " 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/.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..`. // Must be unique and not contain dots. string name = 1; // Endpoint URL. HTTP(S) for streamable-HTTP servers, // `stdio://` 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; }