From 535fd8bb549844d04a876b8b0e2fc66a8bbe58ca Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 02:47:48 +0200 Subject: [PATCH] Glossary: the words of research 053's graduation, and harness and role as homonyms Playbook 02 adds a graduated effort's words; design 58 now says agent harness, never the bare word. --- 00-META/glossary.md | 53 +++++++++++++++---- .../58-agent-work-as-the-meshs-own.md | 12 ++--- 2 files changed, 49 insertions(+), 16 deletions(-) diff --git a/00-META/glossary.md b/00-META/glossary.md index c64dad16..47773150 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -101,8 +101,8 @@ are a published vocabulary, fixed by the manifest's schema. **Decided by** ADR 0 (ADR 0188). - **tool** — one capability a module serves through the tool runner, addressed `.`. A seat's **verb** is the same thing carried by a seat rather than a module. -- **mesh-sdk** — the library a module's own code is written against, including the harness that serves a - tools bundle to the tool runner. The harness is part of it, not a library of its own. +- **mesh-sdk** — the library a module's own code is written against, including the SDK harness that serves a + tools bundle to the tool runner. The SDK harness is part of it, not a library of its own. *Not:* ~~tools-sdk~~ - **invokes** — the manifest word for the tools a module calls, `.` each or `*` for every one. A grant on the publish side and nothing else; a module that declares none calls nothing. @@ -270,8 +270,8 @@ and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221, 02 **Purpose.** To issue, hold, rotate and check the credentials and grants by which modules, nodes, agents and the operator act. **Recorded by** the controller's `identity` and `licences` databases and the vault. **Upstream of** Provisioning, Change and delivery, and Operator and conversation. -**Decided by** ADR 0085, 0113, 0183, 0225, 0234. -**Uses:** module, node, operator, consumer (Provisioning). +**Decided by** ADR 0085, 0113, 0183, 0225, 0234, 0386, 0387, 0388. +**Uses:** module, node, operator, consumer (Provisioning), agent (Operator and conversation), tool (Module). - **credential** — anything that proves an identity: a password, a key, a token. A **pair credential** is the two ends of one credential, the consumer's and the provider's. @@ -283,8 +283,24 @@ and the operator act. **Recorded by** the controller's `identity` and `licences` (ADR 0283). - **vault** — the module that owns every secret (`mesh-vault`, [24 — The secrets vault](../03-DESIGN/01-to-be/24-the-secrets-vault.md)). -- **grant** — what an identity may call or reach, bounded by the provisions it requires - (ADR 0225). +- **identity** — a person, an agent or a module as the mesh knows it: a name, a kind, a role, and whether it + is switched on. Every identity and role is held by the identity seat, in the bus's key-value store, and + changes only through its verbs (ADR 0386). +- **role** — what an identity may call, as a set of grants (ADR 0386). Not a seat: a bare *role* is a + homonym (see [Homonyms](#homonyms)). +- **grant** — one line of a role: an effect everywhere, an effect on one seat, or one named tool, and may be + limited to named machines; a dangerous tool is granted only by name (ADR 0386). A module's grants + come from what its manifest declares it calls, bounded by the provisions it requires (ADR 0225). +- **effect** — a tool's mark, set by its module in its manifest: **reads**, **acts** or **dangerous**; a + tool served without one counts as dangerous (ADR 0387). +- **break-glass agent** — the one agent that holds every tool and never asks: sealed until the operator, or + a condition the operator named, opens it, open until the operator closes it, and every act it takes told + at once (ADR 0387). +- **signed login** — a bus login signed by a key the bus trusts, carrying its expiry, which the bus checks by + its signature instead of reading a list (ADR 0388). The identity seat signs with one **signing key** per + role. +- **root key** — the key at the top of the signed logins, which vouches for the signing keys: sealed in the + vault and used only to replace them, on the operator's Approve (ADR 0388). - **bus account** and **membership** — a module's or a node's account on the bus, and the subjects it is issued. The bus server calls its accounts *users*; the mesh says bus account. - **rotate** — replacing a credential without a consumer holding one the provider does not know. @@ -503,7 +519,7 @@ it should not. **Recorded by** the controller. **Upstream of** Provisioning and trust. **Recorded by** the router (asks, warrants and the operator's identities). **Downstream of** Health and repair, Change and delivery, and Identity and access. An authorising answer acts in whichever domain asked, through that domain's own verb; the conversation owns the -asking, never the act. **Decided by** ADR 0152, 0175, 0234, 0259, 0272. +asking, never the act. **Decided by** ADR 0152, 0175, 0234, 0259, 0272, 0383, 0384, 0385, 0390. **Uses:** operator, person, proof (Identity and access), release (Change and delivery). - **mesh MCP server** — the endpoint on a node's loopback through which every agent and person on that @@ -559,8 +575,21 @@ asking, never the act. **Decided by** ADR 0152, 0175, 0234, 0259, 0272. instructions. - **reference** — an opaque token in a message's words standing for a detail the content rule keeps out of them (a path, an address); opened with `detail` only on a `private` channel or through the mesh MCP server. -- **agent** — a coding agent: the operator's, or one the mesh runs. Not the node-engine, and not the +- **agent** — a coding agent: the operator's, or one the mesh runs; to the mesh, an identity of kind agent + (ADR 0386). Not the node-engine, and not the build seat's holder, whose seat name `node-build-agent` is an identifier to rename. +- **thread** — one line of agent work, owned by the mesh: its turns, tool calls and results, its workspace + and usage, kept whole for good on the bus by the thread seat; it outlives any session, node or front end + (ADR 0383). +- **session** — one run of an agent harness on a thread. +- **agent harness** — the program that runs an agent's sessions, its context manager and loop: Claude Code + today (ADR 0384). Not the SDK harness (see [Homonyms](#homonyms)). +- **thread handler** — the node seat whose holder runs threads' sessions headless, on the always-on nodes + (ADR 0384). +- **workspace toolkit** — the tools a session works with on its thread's workspace, the same for every agent + harness: the node seat `workspace` (ADR 0385). +- **sandbox** — the small virtual machine one session runs in, with its thread's workspace mounted + (ADR 0390). - **instruction section** — one named section of the managed instruction file, which every agent session on the nodes it is for reads first, as the mesh's word: set at the controller's terminal in the agent module's settings, or **proposed** by an agent and made active on each node only by the operator's warrant, which that node @@ -624,7 +653,7 @@ Not a domain of the mesh but of the way it is built, listed because its words me `changed`, `superseded`): a later record may change one clause and leave the rest (ADR 0290). Not a *rule*, which is a line of `00-META/how-we-build.md`. -- **knowledge base** — the role that holds the decision records and research efforts whole (number, status, topic, +- **knowledge base** — what holds the decision records and research efforts whole (number, status, topic, typed links, clauses and reasoning, with every version), takes them as proposals, has them reviewed and accepted, and answers what holds: the seat `knowledge-base`, held by the module `mesh-knowledge` ([55 — The knowledge base](../03-DESIGN/01-to-be/55-the-knowledge-base.md)). Not **the record**, the literal reader @@ -634,7 +663,7 @@ Not a domain of the mesh but of the way it is built, listed because its words me holds it whole: its report, diagnosis and resolution included (ADR 0291); the folders in `04-ISSUES/` are imported there and removed. An **incident** is a past event that taught a rule. -- **issue tracker** — the role that holds the mesh's issues and hands out their numbers: the seat `issue-tracker`, +- **issue tracker** — what holds the mesh's issues and hands out their numbers: the seat `issue-tracker`, held by the module `mesh-issues` ([53 — The issue tracker](../03-DESIGN/01-to-be/53-the-issue-tracker.md)). Not hits's *item*; bare *ticket* is a homonym (see [Homonyms](#homonyms)). *Not:* ~~ticketing system~~ (hq), ~~ticket system~~ (hq) @@ -688,6 +717,10 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical. | tier | a level of the mesh | **layer** | Core | | | a step of a rollout | **tier** | Change and delivery | | | how much proof an ask needs | **assurance level** | Identity and access | +| harness | the part of `mesh-sdk` that serves a tools bundle | **SDK harness** | Module | +| | the program that runs an agent's sessions | **agent harness** | Operator and conversation | +| role | what a seat names, at a scope | **seat** | Module | +| | what an identity may call | **role** | Identity and access | | ask | a request for the operator's input | **ask** | Operator and conversation | | | an entry in the build queue | **build request** | Change and delivery | | store | the one database server | **store** | Core | diff --git a/03-DESIGN/01-to-be/58-agent-work-as-the-meshs-own.md b/03-DESIGN/01-to-be/58-agent-work-as-the-meshs-own.md index cfae3781..a706879c 100644 --- a/03-DESIGN/01-to-be/58-agent-work-as-the-meshs-own.md +++ b/03-DESIGN/01-to-be/58-agent-work-as-the-meshs-own.md @@ -17,7 +17,7 @@ decisions: # 58 — Agent work as the mesh's own **An agent's work belongs to the mesh, not to one vendor's program or one machine. A thread is kept whole on the -bus by a thread seat; a thread handler on an always-on node runs the agent's harness headless for it, in a sandbox +bus by a thread seat; a thread handler on an always-on node runs the agent harness headless for it, in a sandbox of its own, with the thread's own branch on the forge as its workspace; the agent works through a workspace toolkit and named tools, never a general command runner. Every person, agent and module is an identity held by one identity seat, with a role made of grants; the bus checks each login by its signature, and the tool runner checks each call @@ -35,7 +35,7 @@ nothing lost; the agent's calls outside its role are refused, saying which grant ───────── ─────────────── ──────────────── front ends nox-thread-handler nox-threads (seat thread) ├ terminal client (first) ├ takes a thread's lease ├ a restricted stream per thread - ├ web page (then) ├ runs the harness headless ├ the object store for large content + ├ web page (then) ├ runs the agent harness headless ├ the object store for large content └ Telegram: questions, │ inside a microsandbox └ leases in the bus's key-value store approvals ├ answers permission requests │ │ through the mesh's asks identity seat @@ -60,18 +60,18 @@ source of truth: the conversation, the agent's questions and their answers, tool every change of state. Large content goes to the object store and is named from the stream. The stream is restricted (ADR 0376): only modules granted it read it. A thread is never deleted; the trail is kept for good. -A thread is **open**, **assigned** (to a node and a harness), **released** or **stopped**. Its seat's verbs create, +A thread is **open**, **assigned** (to a node and an agent harness), **released** or **stopped**. Its seat's verbs create, assign, release, stop, move it, and take it over with a reason. The assignment is a **lease** in the bus's key-value store, changed only by a compare-and-set on its revision. Its holder renews it every 20 s. A lease not renewed for 60 s is said to the operator; nothing takes it over by itself. ## 3. Running a thread (ADR 0384) -The thread handler on an always-on node takes the lease and starts the harness (Claude Code today) headless, one -turn at a time. It answers the harness's permission requests through the mesh's asks, so a front end answers them in +The thread handler on an always-on node takes the lease and starts the agent harness (Claude Code today) headless, one +turn at a time. It answers the agent harness's permission requests through the mesh's asks, so a front end answers them in place. At the end of every turn it commits and pushes the workspace, which is the thread's own branch on the forge; a node that picks the thread up fetches it, so a move loses at most the turn in progress. Before a shutdown it -releases at a turn boundary; on a stop it ends the process group, since a tool's child process outlives the harness. +releases at a turn boundary; on a stop it ends the process group, since a tool's child process outlives the agent harness. The claude-code module mirrors the session's stream into the thread and, on pick-up, rebuilds a session from the thread. Usage per thread comes from each run's result and rate-limit messages on the stream, not the transcript, and the