From 56a9cccbc5713fa1e47bccfb7fed17722fa39015 Mon Sep 17 00:00:00 2001 From: Preston Holmes Date: Sun, 31 May 2026 14:08:49 +0000 Subject: [PATCH 1/4] Add engineering glossary (GLOSSARY.md) with canonical terms and cleanup tracker Add a root-level GLOSSARY.md capturing canonical Scion terminology in the ubiquitous-language format (preferred term + synonyms to avoid), grouped by domain cluster, plus an Exceptions & Future Cleanup section tracking known naming-convergence work. Link it from agents.md as the canonical engineering glossary. --- GLOSSARY.md | 205 ++++++++++++++++++++++++++++++++++++++++++++++++++++ agents.md | 2 + 2 files changed, 207 insertions(+) create mode 100644 GLOSSARY.md diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 000000000..78c63cd1e --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,205 @@ +# Scion + +Scion is a container-based orchestration platform for running multiple LLM "deep agents" concurrently, each isolated in its own container, workspace, and credentials. This document fixes the preferred term for each domain concept so that code, docs, UI, and prompts share one vocabulary. + +> The concept formerly called *grove* is now **project**, and "broker" alone is never used — always **Runtime Broker** or **Message Broker**. The codebase does not yet fully match either rule; see [Exceptions & Future Cleanup](#exceptions--future-cleanup) for the known gaps. + +## Language + +### Orchestration + +**Agent**: +An isolated worker: one LLM-plus-harness loop in its own container with its own identity, credentials, and workspace. The fundamental unit of execution in Scion. +_Avoid_: worker, bot, instance, process + +**Sub-agent**: +An agent spawned by another agent; "sub" only from the orchestrating user's view, since it is a full agent in capability. +_Avoid_: helper, thread, worker thread + +**Project**: +A namespace and collection of agents and configuration, represented by a `.scion` directory and usually one-to-one with a git repository. +_Avoid_: grove, group, repo, workspace + +**Template**: +A harness-agnostic folder resource defining a generic agent — system prompt, agent instructions, skills, and a default harness-config pointer — with nothing specific to any one harness. +_Avoid_: role, blueprint, profile, config + +**Harness**: +The external, vendor-supplied agent software that Scion drives, such as Claude Code, Gemini CLI, Codex, or OpenCode. Provided outside Scion; Scion only configures and runs it. +_Avoid_: model, backend, driver, tool + +**Harness-config**: +A named, reusable snapshot of settings for a particular harness — which harness, plus its image, auth, secrets, model settings, and skills. The configuration *of* a harness, distinct from the harness itself. +_Avoid_: harness, harness adapter, integration, plugin + +**Skill**: +A reusable instruction snippet contributed by a template or harness-config and mounted into the harness's skills directory at provisioning. +_Avoid_: prompt snippet, macro, plugin + +**Plugin**: +An out-of-process extension built on `hashicorp/go-plugin` (gRPC) that supplies a message broker or harness implementation without modifying Scion core. +_Avoid_: extension, addon, module, skill + +**sciontool**: +The helper utility injected into every agent container for status reporting, metadata access, and task management. +_Avoid_: agent tool, scion-tool + +### Runtime & Workspace + +**Runtime**: +The container technology that executes an agent's container: Docker, Podman, Apple Container, or Kubernetes. +_Avoid_: backend, engine, executor, environment + +**Profile**: +A named bundle of runtime broker settings selected as a unit — a runtime plus its execution settings (env, volumes, resources), default harness-config and template, image registry, secrets, and harness overrides. A runtime-broker-scoped concept; long form **Runtime Broker Profile**. +_Avoid_: environment, runtime config, preset, runtime profile + +**Workspace**: +The working directory mounted into a single agent's container at `/workspace`, isolated as a git worktree (local) or a fresh checkout (Hub). +_Avoid_: project, repo, mount + +**Shared Directory**: +A persistent, mutable volume shared by the agents within one project. +_Avoid_: shared mount, shared volume, common dir + +**Agent home**: +The directory mounted as the container user's home folder, holding that agent's unique config and history. +_Avoid_: home mount, config dir + +### Hub & Hosted + +**Hub**: +The centralized control plane of a hosted deployment, owning identity, auth, project registration, and state, and dispatching commands to runtime brokers. +_Avoid_: server, control plane, master, coordinator + +**Runtime Broker**: +A compute node (laptop, VM, or cluster) that registers with a Hub to offer execution capacity and runs the agents dispatched to it. Always write in full; "broker" alone is forbidden because it collides with Message Broker. +_Avoid_: broker, node, runner, worker + +**Message Broker**: +The NATS-based backend that routes messages between agents and users over `scion.*` topics. Always write in full; "broker" alone is forbidden because it collides with Runtime Broker. +_Avoid_: broker, message bus, queue, pub/sub + +> **Disambiguation rule:** Never use bare "broker" in prose, comments, docs, or new identifiers — always qualify it as **Runtime Broker** or **Message Broker**. Existing bare usages in code are documented exceptions; see [Exceptions & Future Cleanup](#exceptions--future-cleanup). + +**Hub-native project**: +A project created on a Hub for dispatched agents, living at `~/.scion/projects/` on each providing broker, identified by a random UUID v4. +_Avoid_: hub-project, hosted project, cloud project + +**Linked project**: +A project that already existed on a broker machine and is linked to a Hub for cross-broker visibility, identified by a deterministic UUID v5 from its git URL. +_Avoid_: local project, imported project, registered project + +**Server**: +The `scion server` command group, and the single combined process it manages — one or more server components run together as a background daemon (or with `--foreground`) via `start`/`stop`/`restart`/`status`. +_Avoid_: daemon, service, backend + +**Server component**: +One of the roles a server process can run — the Hub API, the Runtime Broker API, or the Web dashboard. A single server process may run any combination of these. +_Avoid_: service, module, role + +**Combo server**: +A server process running both the Hub and Runtime Broker components together (the default in workstation mode). +_Avoid_: hub-broker, all-in-one, standalone, monolith + +### Users & Access + +**Group**: +A named collection of Hub users (and nested groups) used by the Hub permissions system to assign access. This is the primary meaning of "group" in Scion. +_Avoid_: team, org, role + +### Messaging + +**Message Group**: +A set of recipients addressed by a single send, correlated by a shared `group_id`, as opposed to a direct message to one recipient or a broadcast to all agents in a project. +_Avoid_: group, set, group chat, room, thread + +### Identity & State + +**Project ID**: +A project's unique identifier: UUID v5 derived from the normalized git URL for git-backed projects, random UUID v4 for hub-native projects. +_Avoid_: grove ID, project key, repo ID, slug + +**Ancestry chain**: +The tracked `root → parent → child` relationship between agents that governs transitive access control. +_Avoid_: lineage, hierarchy, agent tree, family + +**Phase**: +The infrastructure lifecycle stage of an agent container, from `created` through `running` to `stopped` or `error`. +_Avoid_: status, stage, lifecycle state + +**Activity**: +What a running agent is currently doing, such as `thinking`, `executing`, `waiting_for_input`, or `blocked`. Distinct from phase. +_Avoid_: status, state, mode + +**Blocked**: +The activity an agent assigns to itself when intentionally waiting for an expected event, so it is not mistaken for stalled. +_Avoid_: stalled, stuck, idle, waiting + +### Modes + +**Local mode**: +Running Scion with no server at all — agents launched directly via the `scion` CLI, with state on the local machine and isolation via git worktrees. +_Avoid_: solo mode, standalone mode, single-user mode, workstation mode + +**Workstation mode**: +Running a single-tenant Scion server (Hub + Runtime Broker + Web combined) on your own machine, giving the hosted experience locally over loopback. A local server, not the no-server CLI workflow. +_Avoid_: local mode, local server, dev mode, single-user mode + +**Hosted mode**: +The umbrella term for running against a Hub that coordinates state across users, projects, and runtime brokers; a multi-user server deployment is the canonical example. +_Avoid_: hub mode, cloud mode, distributed mode, production mode + +**Attach**: +Connecting an interactive terminal to a running agent's tmux session for human-in-the-loop interaction; the agent keeps running once detached. +_Avoid_: connect, join, ssh in + +**Dispatch**: +The Hub handing an agent lifecycle command to the appropriate runtime broker for execution. +_Avoid_: schedule, route, assign, delegate + +## Exceptions & Future Cleanup + +Known places where the codebase does not yet match this glossary. These are **documented exceptions, not precedents** — always use the canonical term in new work. + +### grove → project + +"grove" was renamed to **project** but remains throughout the code as intentional backward-compat: JSON wire fields (`groveId`, `grove`), container labels (`scion.grove*`), env vars (`SCION_GROVE*`), NATS topics (`scion.grove..*`), SQL schema history, deprecated `--grove` CLI flags, and `/api/v1/groves/*` endpoints. + +- **Safe now:** internal variable/function names, comments, log messages, and design docs may be renamed `grove` → `project` freely. +- **Future cleanup (needs coordination):** wire-format JSON tags, container labels, env vars, NATS topic prefix, and SQL schema should converge to `project` only at a breaking-change/version boundary. + +### Bare "broker" is ambiguous + +The two broker concepts collide on the unqualified word, and the two existing bare usages point in **opposite directions**: + +- `scion broker` CLI command → **Runtime Broker** +- `pkg/broker` package → **Message Broker** + +- **Safe now:** all new prose, comments, docs, and identifiers must qualify the term as **Runtime Broker** or **Message Broker**. +- **Future cleanup (needs coordination):** consider renaming `pkg/broker` → `pkg/messagebroker` and/or the `scion broker` command to a qualified form so no bare "broker" remains. + +### Message-group naming: `set` → `group` + +The **Message Group** concept is currently named "set" in code — `SetRecipient`, `sendSetMessageViaHub`, `setRecipient` (`cmd/message.go`, `pkg/messages`). "set" is not the canonical term. + +- **Future cleanup:** rename the "set" recipient/message types and helpers to "group" (e.g. `SetRecipient` → group recipient) so the code matches **Message Group**. Note this is only safe now that **Group** (hub users) and **Message Group** are clearly distinguished — the rename must not blur them. +- **Related — `broadcast`:** the term "broadcast" (a message to all agents in a project, e.g. `BroadcastTopic` in `pkg/broker/broker.go`) sits alongside Message Group and direct messages. Review whether "broadcast" should be retained, redefined, or folded into the message-group vocabulary as part of the same cleanup. + +### `scion server` mode vocabulary + +The canonical server modes are **Workstation mode** (single-tenant, on your own machine) and **Hosted mode** (multi-user deployment). The `scion server` command group does not yet use this vocabulary consistently: + +- "local" still leaks in for the workstation case (e.g. "local server" at `cmd/server.go:100`). +- The non-workstation mode is named "production" (`--production` flag, "Production mode" in help text in `cmd/server.go`). + +- **Future cleanup:** converge the `scion server` command group's mode terminology to the canonical set — `local` → `workstation`, and `production` → `hosted` (flag name, mode labels, help text, comments) — so the command vocabulary matches **Workstation mode** and **Hosted mode**, and neither is confused with **Local mode** (the no-server CLI workflow). A flag rename like `--production` → `--hosted` is a user-facing change and should keep a deprecated alias. + +### Templates → fully harness-agnostic + +A **Template** must contain nothing harness-specific (the `harness` field is already deprecated in `scion-agent.yaml`), but residual harness-specific bits remain: + +- `templates.md` still documents `image`/`model`/`auth` as template `config.yaml` params, yet the container image belongs to the **Harness-config** — a template should only *override* it. +- Model selection should use a harness-agnostic **S / M / L size alias** rather than harness-specific model names. *(Tracked in an existing open issue.)* + +- **Future cleanup:** move the remaining harness-specific fields out of templates onto the harness-config, and adopt the agnostic model-size alias, so templates are strictly harness-agnostic. diff --git a/agents.md b/agents.md index 667d4e4c3..d4f887f73 100644 --- a/agents.md +++ b/agents.md @@ -84,6 +84,8 @@ All icons in the web frontend use the Shoelace `` component (Bootstrap ## Short hand gossary and project development terminology +> **Canonical engineering glossary:** See [`GLOSSARY.md`](./GLOSSARY.md) at the repo root for the canonical, opinionated terminology used throughout the codebase — the preferred term for each concept and the synonyms to avoid. Prefer these terms in new code, comments, and docs. + These terms may be used in shorthand with prompts - **hub-broker, combo server** References running the server command with both the hub function and the broker function running in the same invocation. From 9d2ae466ffb1c7b4a2d2ed1a21c68de6435b1a76 Mon Sep 17 00:00:00 2001 From: Preston Holmes Date: Sun, 31 May 2026 14:43:00 +0000 Subject: [PATCH 2/4] Revise glossary: broker reframe, Event Bus, Hub-managed, and term refinements Refine entries from review: redefine Message Broker as the pluggable messaging-integration system (add Broker plugin, Built-in broker); add Event Bus for the NATS real-time/event capability; collapse hub-native/Hub Workspace into Hub-managed project/workspace; tighten Template (harness-agnostic, optional default harness-config), Skill (template-only, Agent Skills link), Profile (named runtime-broker settings bundle), Harness/Harness-config; reframe Hub as the control plane in both modes; add Group and Message Group. Expand Exceptions & Future Cleanup to nine tracked items. --- GLOSSARY.md | 61 ++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index 78c63cd1e..ab6a219bc 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -21,7 +21,7 @@ A namespace and collection of agents and configuration, represented by a `.scion _Avoid_: grove, group, repo, workspace **Template**: -A harness-agnostic folder resource defining a generic agent — system prompt, agent instructions, skills, and a default harness-config pointer — with nothing specific to any one harness. +A harness-agnostic folder resource defining a generic agent — its system prompt, agent instructions, skills, services, and more — containing nothing specific to any one harness. A default harness-config may optionally be named, but is not required. _Avoid_: role, blueprint, profile, config **Harness**: @@ -33,7 +33,7 @@ A named, reusable snapshot of settings for a particular harness — which harnes _Avoid_: harness, harness adapter, integration, plugin **Skill**: -A reusable instruction snippet contributed by a template or harness-config and mounted into the harness's skills directory at provisioning. +A reusable, harness-agnostic instruction snippet contributed by a template and mounted into the harness's skills directory at provisioning. Follows the open [Agent Skills](https://agentskills.io/home) convention. _Avoid_: prompt snippet, macro, plugin **Plugin**: @@ -69,22 +69,34 @@ _Avoid_: home mount, config dir ### Hub & Hosted **Hub**: -The centralized control plane of a hosted deployment, owning identity, auth, project registration, and state, and dispatching commands to runtime brokers. -_Avoid_: server, control plane, master, coordinator +The control plane of Scion — it owns identity, auth, project registration, and state, exposes the APIs and notifications that agents and users interact with, and dispatches commands to runtime brokers. Present in both workstation and hosted mode, not only hosted. +_Avoid_: server, master, coordinator **Runtime Broker**: A compute node (laptop, VM, or cluster) that registers with a Hub to offer execution capacity and runs the agents dispatched to it. Always write in full; "broker" alone is forbidden because it collides with Message Broker. _Avoid_: broker, node, runner, worker **Message Broker**: -The NATS-based backend that routes messages between agents and users over `scion.*` topics. Always write in full; "broker" alone is forbidden because it collides with Runtime Broker. +The pluggable system that brokers messages between Scion actors (agents and users) and messaging surfaces — built-in brokers such as the web UI Messages view, and broker plugins to external systems like Telegram and Google Chat (Discord and Slack planned). Backs the `scion message` command. Always write in full; "broker" alone is forbidden because it collides with Runtime Broker. _Avoid_: broker, message bus, queue, pub/sub -> **Disambiguation rule:** Never use bare "broker" in prose, comments, docs, or new identifiers — always qualify it as **Runtime Broker** or **Message Broker**. Existing bare usages in code are documented exceptions; see [Exceptions & Future Cleanup](#exceptions--future-cleanup). +**Broker plugin**: +A Message Broker implementation for a specific external messaging system (e.g. Telegram, Google Chat), loaded through the broker plugin interface (`PluginTypeBroker`). +_Avoid_: connector, bridge, adapter -**Hub-native project**: -A project created on a Hub for dispatched agents, living at `~/.scion/projects/` on each providing broker, identified by a random UUID v4. -_Avoid_: hub-project, hosted project, cloud project +**Built-in broker**: +A Message Broker implementation shipped with Scion rather than loaded as a plugin — for example the broker that surfaces messages in the web UI's Messages view. +_Avoid_: native broker, internal broker, default broker + +> **Disambiguation rule:** Never use bare "broker" in prose, comments, docs, or new identifiers — always qualify it as **Runtime Broker** or **Message Broker**. Note that `pkg/broker` (NATS-style pub/sub) is *not* the Message Broker; it underpins the **Event Bus**. Existing bare usages in code are documented exceptions; see [Exceptions & Future Cleanup](#exceptions--future-cleanup). + +**Event Bus**: +The NATS-style pub/sub system (`pkg/broker`) that brokers and dispatches real-time change events to live web views via server-sent events, supporting the move to a more stateless Hub. Distinct from the Message Broker; currently a latent capability. +_Avoid_: message broker, broker, change feed, live sync, event stream + +**Hub-managed project**: +A project whose workspace is created and managed by Scion in the hub-controlled part of the broker filesystem (`~/.scion/projects//`), shared across the project's agents — as opposed to a Linked project that points at a pre-existing path. Identified by a random UUID v4. The workspace itself is the **Hub-managed workspace**. +_Avoid_: hub-native, hub-native project, hub workspace, hub-project, hosted project, cloud project **Linked project**: A project that already existed on a broker machine and is linked to a Hub for cross-broker visibility, identified by a deterministic UUID v5 from its git URL. @@ -117,7 +129,7 @@ _Avoid_: group, set, group chat, room, thread ### Identity & State **Project ID**: -A project's unique identifier: UUID v5 derived from the normalized git URL for git-backed projects, random UUID v4 for hub-native projects. +A project's unique identifier: UUID v5 derived from the normalized git URL for git-backed projects, random UUID v4 for hub-managed projects. _Avoid_: grove ID, project key, repo ID, slug **Ancestry chain**: @@ -169,15 +181,28 @@ Known places where the codebase does not yet match this glossary. These are **do - **Safe now:** internal variable/function names, comments, log messages, and design docs may be renamed `grove` → `project` freely. - **Future cleanup (needs coordination):** wire-format JSON tags, container labels, env vars, NATS topic prefix, and SQL schema should converge to `project` only at a breaking-change/version boundary. -### Bare "broker" is ambiguous +### Bare "broker" is ambiguous (three-way) -The two broker concepts collide on the unqualified word, and the two existing bare usages point in **opposite directions**: +"broker" is unqualified across three distinct concepts: - `scion broker` CLI command → **Runtime Broker** -- `pkg/broker` package → **Message Broker** +- `PluginTypeBroker` / broker plugins → **Message Broker** (the canonical messaging-integration system) +- `pkg/broker` package (NATS-style pub/sub) → the **Event Bus** (see next item), *not* the Message Broker + +- **Safe now:** qualify "broker" in all new prose and identifiers; reserve **Message Broker** for the messaging-integration system only. +- **Future cleanup (needs coordination):** rename `pkg/broker` to the **Event Bus** (e.g. `pkg/eventbus`), and consider qualifying the `scion broker` command, so bare "broker" no longer spans three meanings. + +### Event Bus: rename `pkg/broker` + +The NATS-style pub/sub in `pkg/broker` is the **Event Bus** — a latent capability for brokering and dispatching real-time change events to live web views (via server-sent events) as the Hub moves to a more stateless serving model. It is *not* the Message Broker and should not be called one. -- **Safe now:** all new prose, comments, docs, and identifiers must qualify the term as **Runtime Broker** or **Message Broker**. -- **Future cleanup (needs coordination):** consider renaming `pkg/broker` → `pkg/messagebroker` and/or the `scion broker` command to a qualified form so no bare "broker" remains. +- **Future cleanup:** rename `pkg/broker` and its identifiers to **Event Bus** (e.g. `pkg/eventbus`) so the code reflects the term and is not confused with the Message Broker. + +### Reconcile `hub-native` / "Hub Workspace" → Hub-managed + +The same concept — a project whose workspace is created and managed in the hub-controlled broker FS — is called **`hub-native`** in code (`ProjectType = 'hub-native'`) and **"Hub Workspace"** in the web UI (new-project dialog `value="hub"`, `git-remote-display.ts`). Canonical term is now **Hub-managed project** (workspace: **Hub-managed workspace**). + +- **Future cleanup:** converge both to "hub-managed" — web `ProjectType`/labels (`web/src/shared/types.ts`, `project-create.ts`, `git-remote-display.ts`), Go identifiers/comments (`findAgentInHubNativeProjects`, `pkg/runtimebroker/handlers.go`, storage paths in `pkg/storage/storage.go`), and docs — keeping wire/string-value backward-compat where the type string crosses the API. ### Message-group naming: `set` → `group` @@ -203,3 +228,9 @@ A **Template** must contain nothing harness-specific (the `harness` field is alr - Model selection should use a harness-agnostic **S / M / L size alias** rather than harness-specific model names. *(Tracked in an existing open issue.)* - **Future cleanup:** move the remaining harness-specific fields out of templates onto the harness-config, and adopt the agnostic model-size alias, so templates are strictly harness-agnostic. + +### Skills should be template-only + +A **Skill** should be contributed only by a **Template**, but provisioning currently also copies skills from the harness-config base layer: `pkg/agent/provision.go:596-605` copies `/skills`, then `:607-618` overlays each template's `skills`. `templates.md` likewise documents skills coming from both templates and harness-configs. + +- **Future cleanup:** make templates the sole source of skills — remove the harness-config skill-copy step (and update the docs) so skills are template-only and harness-agnostic, consistent with the [Agent Skills](https://agentskills.io/home) convention. From 2401e65febd253188760e90e8bd45cf30bcfdd80 Mon Sep 17 00:00:00 2001 From: Preston Holmes Date: Sun, 31 May 2026 16:16:06 +0000 Subject: [PATCH 3/4] Glossary: restructure headings, add cross-refs, modes table, and new terms - Retitle to "Scion Glossary"; drop the "Language" wrapper and promote the thematic categories to top-level sections - Add an Operations section (Attach, Dispatch) and move Profile next to Runtime Broker - Add a Local/Workstation/Hosted comparison table and "See also" cross-refs across the main confusable term clusters - Reframe the intro around the three-way broker collision (incl. Event Bus) and defer to the disambiguation rule; sentence-case "Shared directory" - Add canonical entries for Secret, Notification, and Schedule - Add a "Potential Future Additions" section cataloguing candidate terms --- GLOSSARY.md | 149 ++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 127 insertions(+), 22 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index ab6a219bc..cbeef2a63 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -1,12 +1,10 @@ -# Scion +# Scion Glossary Scion is a container-based orchestration platform for running multiple LLM "deep agents" concurrently, each isolated in its own container, workspace, and credentials. This document fixes the preferred term for each domain concept so that code, docs, UI, and prompts share one vocabulary. -> The concept formerly called *grove* is now **project**, and "broker" alone is never used — always **Runtime Broker** or **Message Broker**. The codebase does not yet fully match either rule; see [Exceptions & Future Cleanup](#exceptions--future-cleanup) for the known gaps. +> Two naming rules run throughout: the concept formerly called *grove* is now **project**, and bare **"broker"** is never used on its own — it is ambiguous across three distinct concepts (**Runtime Broker**, **Message Broker**, and the **Event Bus**), so it must always be qualified (see the disambiguation rule under [Hub & Hosted](#hub--hosted)). The codebase does not yet fully match either rule; see [Exceptions & Future Cleanup](#exceptions--future-cleanup) for the known gaps. -## Language - -### Orchestration +## Orchestration **Agent**: An isolated worker: one LLM-plus-harness loop in its own container with its own identity, credentials, and workspace. The fundamental unit of execution in Scion. @@ -23,42 +21,64 @@ _Avoid_: grove, group, repo, workspace **Template**: A harness-agnostic folder resource defining a generic agent — its system prompt, agent instructions, skills, services, and more — containing nothing specific to any one harness. A default harness-config may optionally be named, but is not required. _Avoid_: role, blueprint, profile, config +_See also_: Harness-config (its harness-specific counterpart), Skill **Harness**: The external, vendor-supplied agent software that Scion drives, such as Claude Code, Gemini CLI, Codex, or OpenCode. Provided outside Scion; Scion only configures and runs it. _Avoid_: model, backend, driver, tool +_See also_: Harness-config **Harness-config**: -A named, reusable snapshot of settings for a particular harness — which harness, plus its image, auth, secrets, model settings, and skills. The configuration *of* a harness, distinct from the harness itself. +A named, reusable, harness-specific resource that configures a particular harness — which harness, plus its image, auth, secrets, model settings, and skills. The harness-specific counterpart to the (harness-agnostic) **Template**, and extensible the same way via a container-script provisioner rather than compiled-in logic. _Avoid_: harness, harness adapter, integration, plugin +_See also_: Template, Harness, Container-script provisioner + +**Container-script provisioner**: +The script-based provisioning model (`provisioner.type: container-script`) by which a harness-config extends agent setup with a container-side `provision.py`, making harness provisioning extensible — as opposed to a compiled-in (built-in) provisioner. +_Avoid_: built-in provisioner, plugin provisioner, install script, provision hook **Skill**: A reusable, harness-agnostic instruction snippet contributed by a template and mounted into the harness's skills directory at provisioning. Follows the open [Agent Skills](https://agentskills.io/home) convention. _Avoid_: prompt snippet, macro, plugin +_See also_: Template, Plugin **Plugin**: -An out-of-process extension built on `hashicorp/go-plugin` (gRPC) that supplies a message broker or harness implementation without modifying Scion core. +An out-of-process extension built on `hashicorp/go-plugin` (gRPC) that supplies a Message Broker implementation without modifying Scion core. Harness implementations are *not* offered as plugins; additional plugin types may be added in future. _Avoid_: extension, addon, module, skill +_See also_: Broker plugin, Message Broker **sciontool**: The helper utility injected into every agent container for status reporting, metadata access, and task management. _Avoid_: agent tool, scion-tool -### Runtime & Workspace +## Runtime & Workspace **Runtime**: The container technology that executes an agent's container: Docker, Podman, Apple Container, or Kubernetes. _Avoid_: backend, engine, executor, environment - -**Profile**: -A named bundle of runtime broker settings selected as a unit — a runtime plus its execution settings (env, volumes, resources), default harness-config and template, image registry, secrets, and harness overrides. A runtime-broker-scoped concept; long form **Runtime Broker Profile**. -_Avoid_: environment, runtime config, preset, runtime profile +_See also_: Runtime Broker, Profile **Workspace**: -The working directory mounted into a single agent's container at `/workspace`, isolated as a git worktree (local) or a fresh checkout (Hub). +The working directory mounted into a single agent's container at `/workspace`. How it is provisioned across a project's agents is set by the project's **workspace sharing mode**. _Avoid_: project, repo, mount -**Shared Directory**: +**Workspace sharing mode**: +How a project's workspace is provisioned across its agents — one universal set of modes intended for both local and Hub-managed projects: **Shared-plain**, **Worktree-per-agent**, and **Clone-per-agent**. +_Avoid_: workspace mode, isolation mode + +**Shared-plain**: +A workspace sharing mode where one workspace directory is mounted into every agent with no per-agent isolation — the model used for plain (non-git) projects. +_Avoid_: shared mount, plain workspace + +**Worktree-per-agent**: +A workspace sharing mode where each agent gets its own git worktree over a shared checkout, isolating working trees while sharing one clone's history. Supported in local mode today; not yet on Hub-managed projects. +_Avoid_: worktree mode, shared checkout + +**Clone-per-agent**: +A workspace sharing mode where each agent gets its own full git clone of the repository. +_Avoid_: clone mode, per-agent clone + +**Shared directory**: A persistent, mutable volume shared by the agents within one project. _Avoid_: shared mount, shared volume, common dir @@ -66,7 +86,7 @@ _Avoid_: shared mount, shared volume, common dir The directory mounted as the container user's home folder, holding that agent's unique config and history. _Avoid_: home mount, config dir -### Hub & Hosted +## Hub & Hosted **Hub**: The control plane of Scion — it owns identity, auth, project registration, and state, exposes the APIs and notifications that agents and users interact with, and dispatches commands to runtime brokers. Present in both workstation and hosted mode, not only hosted. @@ -75,31 +95,41 @@ _Avoid_: server, master, coordinator **Runtime Broker**: A compute node (laptop, VM, or cluster) that registers with a Hub to offer execution capacity and runs the agents dispatched to it. Always write in full; "broker" alone is forbidden because it collides with Message Broker. _Avoid_: broker, node, runner, worker +_See also_: Runtime, Profile, Message Broker (distinct concept, same word) + +**Profile**: +A named bundle of runtime broker settings selected as a unit — a runtime plus its execution settings (env, volumes, resources), default harness-config and template, image registry, secrets, and harness overrides. A runtime-broker-scoped concept; long form **Runtime Broker Profile**. +_Avoid_: environment, runtime config, preset, runtime profile +_See also_: Runtime Broker, Runtime **Message Broker**: The pluggable system that brokers messages between Scion actors (agents and users) and messaging surfaces — built-in brokers such as the web UI Messages view, and broker plugins to external systems like Telegram and Google Chat (Discord and Slack planned). Backs the `scion message` command. Always write in full; "broker" alone is forbidden because it collides with Runtime Broker. _Avoid_: broker, message bus, queue, pub/sub +_See also_: Broker plugin, Built-in broker, Plugin, Event Bus (distinct), Runtime Broker (distinct, same word) **Broker plugin**: A Message Broker implementation for a specific external messaging system (e.g. Telegram, Google Chat), loaded through the broker plugin interface (`PluginTypeBroker`). _Avoid_: connector, bridge, adapter +_See also_: Message Broker, Built-in broker, Plugin **Built-in broker**: A Message Broker implementation shipped with Scion rather than loaded as a plugin — for example the broker that surfaces messages in the web UI's Messages view. _Avoid_: native broker, internal broker, default broker +_See also_: Message Broker, Broker plugin > **Disambiguation rule:** Never use bare "broker" in prose, comments, docs, or new identifiers — always qualify it as **Runtime Broker** or **Message Broker**. Note that `pkg/broker` (NATS-style pub/sub) is *not* the Message Broker; it underpins the **Event Bus**. Existing bare usages in code are documented exceptions; see [Exceptions & Future Cleanup](#exceptions--future-cleanup). **Event Bus**: The NATS-style pub/sub system (`pkg/broker`) that brokers and dispatches real-time change events to live web views via server-sent events, supporting the move to a more stateless Hub. Distinct from the Message Broker; currently a latent capability. _Avoid_: message broker, broker, change feed, live sync, event stream +_See also_: Message Broker (distinct concept) **Hub-managed project**: -A project whose workspace is created and managed by Scion in the hub-controlled part of the broker filesystem (`~/.scion/projects//`), shared across the project's agents — as opposed to a Linked project that points at a pre-existing path. Identified by a random UUID v4. The workspace itself is the **Hub-managed workspace**. +A project whose workspace is created and managed by Scion in the hub-controlled part of the broker filesystem (`~/.scion/projects//`), shared across the project's agents — as opposed to a Linked project that points at a pre-existing path. May be plain (no git) or git-backed; git-backed hub-managed projects may share a remote with other projects. The workspace itself is the **Hub-managed workspace**. _Avoid_: hub-native, hub-native project, hub workspace, hub-project, hosted project, cloud project **Linked project**: -A project that already existed on a broker machine and is linked to a Hub for cross-broker visibility, identified by a deterministic UUID v5 from its git URL. +A project whose workspace is a pre-existing path on a broker machine, linked to a Hub for cross-broker visibility — as opposed to a Hub-managed project. May be plain or git-backed. _Avoid_: local project, imported project, registered project **Server**: @@ -114,22 +144,34 @@ _Avoid_: service, module, role A server process running both the Hub and Runtime Broker components together (the default in workstation mode). _Avoid_: hub-broker, all-in-one, standalone, monolith -### Users & Access +**Secret**: +A credential made available to an agent at runtime (e.g. API keys, tokens). A harness-config's `secrets` field *declares* which secrets an agent needs; the **Secret Backend** — a pluggable store (local SQLite for development, GCP Secret Manager in production, selected via `SCION_SERVER_SECRETS_BACKEND`) — *stores and resolves* them, scoped by user, project, runtime broker, or hub, and injects them into the container. Also holds the Hub's signing keys. +_Avoid_: credential, vault, secret store, env secret +_See also_: Harness-config, Profile + +## Users & Access **Group**: A named collection of Hub users (and nested groups) used by the Hub permissions system to assign access. This is the primary meaning of "group" in Scion. _Avoid_: team, org, role +_See also_: Message Group (different concept — message recipients, not users) -### Messaging +## Messaging **Message Group**: A set of recipients addressed by a single send, correlated by a shared `group_id`, as opposed to a direct message to one recipient or a broadcast to all agents in a project. _Avoid_: group, set, group chat, room, thread +_See also_: Group (different concept — hub users, not recipients) -### Identity & State +**Notification**: +An event delivered when an agent reaches a tracked trigger activity (e.g. `completed`, `waiting_for_input`, `limits_exceeded`). Recipients register a **Subscription** — scoped to a single agent or to a whole project, naming which trigger activities fire it and whether an agent or a user receives it. Backs `scion notifications` and the `--notify` flag on `scion message`. +_Avoid_: alert, event (for the notification), watch (for the subscription) +_See also_: Activity (notifications fire on activity values) + +## Identity & State **Project ID**: -A project's unique identifier: UUID v5 derived from the normalized git URL for git-backed projects, random UUID v4 for hub-managed projects. +A project's unique identifier — always a randomly generated UUID. A git remote is associated metadata, not identity, so multiple projects may share the same remote by design. _Avoid_: grove ID, project key, repo ID, slug **Ancestry chain**: @@ -139,16 +181,27 @@ _Avoid_: lineage, hierarchy, agent tree, family **Phase**: The infrastructure lifecycle stage of an agent container, from `created` through `running` to `stopped` or `error`. _Avoid_: status, stage, lifecycle state +_See also_: Activity (what the agent is *doing*, vs. its container stage) **Activity**: What a running agent is currently doing, such as `thinking`, `executing`, `waiting_for_input`, or `blocked`. Distinct from phase. _Avoid_: status, state, mode +_See also_: Phase (the container stage), Blocked (a specific activity value) **Blocked**: The activity an agent assigns to itself when intentionally waiting for an expected event, so it is not mistaken for stalled. _Avoid_: stalled, stuck, idle, waiting +_See also_: Activity (Blocked is one of its values) + +## Modes -### Modes +The three run modes at a glance — distinguish them by whether a server runs and who it serves: + +| Mode | Server | Tenancy | State & isolation | Canonical use | +|------|--------|---------|-------------------|----------------| +| **Local mode** | None | Single user | Local machine; isolation via git worktrees | Agents launched directly via the `scion` CLI, no server | +| **Workstation mode** | Combo server (Hub + Runtime Broker + Web) on loopback | Single-tenant | That machine | The hosted experience locally, on your own machine | +| **Hosted mode** | Multi-user server deployment | Multi-user | Hub-coordinated across brokers | Coordinating state across users, projects, and runtime brokers | **Local mode**: Running Scion with no server at all — agents launched directly via the `scion` CLI, with state on the local machine and isolation via git worktrees. @@ -162,6 +215,8 @@ _Avoid_: local mode, local server, dev mode, single-user mode The umbrella term for running against a Hub that coordinates state across users, projects, and runtime brokers; a multi-user server deployment is the canonical example. _Avoid_: hub mode, cloud mode, distributed mode, production mode +## Operations + **Attach**: Connecting an interactive terminal to a running agent's tmux session for human-in-the-loop interaction; the agent keeps running once detached. _Avoid_: connect, join, ssh in @@ -170,6 +225,29 @@ _Avoid_: connect, join, ssh in The Hub handing an agent lifecycle command to the appropriate runtime broker for execution. _Avoid_: schedule, route, assign, delegate +**Schedule**: +A time-based trigger that fires an action — sending a message or dispatching (starting) an agent from a template — either once (a one-shot *scheduled event*, via `--at