freemo
c2db74ba81
CI / lint (push) Successful in 15s
CI / build (push) Successful in 16s
CI / quality (push) Successful in 20s
CI / security (push) Successful in 35s
CI / typecheck (push) Successful in 42s
CI / benchmark-regression (push) Has been skipped
CI / unit_tests (push) Successful in 2m38s
CI / integration_tests (push) Successful in 3m11s
CI / docker (push) Successful in 39s
CI / coverage (push) Successful in 4m58s
CI / benchmark-publish (push) Successful in 17m32s
130 lines
6.9 KiB
Markdown
130 lines
6.9 KiB
Markdown
---
|
|
adr_number: 2
|
|
title: Namespace System
|
|
status_history:
|
|
- - '2026-02-16'
|
|
- Proposed
|
|
- Jeffrey Phillips Freeman
|
|
- - '2026-02-16'
|
|
- Accepted
|
|
- Jeffrey Phillips Freeman
|
|
tier: 1
|
|
authors:
|
|
- Jeffrey Phillips Freeman
|
|
superseded_by: null
|
|
related_adrs:
|
|
- number: 9
|
|
title: Project Model
|
|
relationship: Projects are namespace-scoped entities that use the naming convention
|
|
- number: 10
|
|
title: Actor and Agent Architecture
|
|
relationship: Actors and agents are identified and resolved via namespaced names
|
|
- number: 11
|
|
title: Tool System
|
|
relationship: Tools use namespaced identifiers for discovery and conflict resolution
|
|
- number: 12
|
|
title: Skill System
|
|
relationship: Skills use namespaced names and resolve tool name conflicts via qualification
|
|
- number: 23
|
|
title: Server Mode
|
|
relationship: Server mode introduces server-prefixed namespaces for multi-server resolution
|
|
acceptance:
|
|
votes_for:
|
|
- voter: Jeffrey Phillips Freeman <Jeffrey.Freeman@CleverThis.com>
|
|
comment: A universal naming scheme avoids ambiguity and makes entity resolution predictable across all contexts
|
|
votes_against: []
|
|
abstentions: []
|
|
---
|
|
## Context
|
|
|
|
CleverAgents manages a wide variety of named entities — actors, tools, skills, resources, resource types, actions, projects, and plans. These entities must be uniquely identifiable, scopeable to different ownership levels (local machine, personal server account, organization), and discoverable across deployment boundaries. Without a uniform naming scheme, entity references would be ambiguous, collision-prone, and incompatible between local and server modes.
|
|
|
|
The system must also support connecting to multiple servers simultaneously and resolving names unambiguously in that context.
|
|
|
|
## Decision Drivers
|
|
|
|
- Entities (actors, tools, skills, resources, projects, plans) must be uniquely identifiable across deployment boundaries
|
|
- Must support multiple ownership scopes: local machine, personal server account, and organization
|
|
- Local-first development must work with zero server configuration
|
|
- System must handle simultaneous connections to multiple servers without name collisions
|
|
- Naming scheme must be uniform across all entity types to reduce cognitive overhead
|
|
- Transition from local-only to shared/collaborative usage should not require structural migration
|
|
|
|
## Decision
|
|
|
|
All named entities in CleverAgents use a universal **namespace-qualified name** format: `[[server:]namespace/]name`. Four namespace types define ownership and storage scope. The `local/` namespace is the default when no namespace is specified.
|
|
|
|
## Design
|
|
|
|
### Name Format
|
|
|
|
The fully qualified form is `server:namespace/name`. Components may be omitted with well-defined defaults:
|
|
|
|
| Form | Resolution |
|
|
|------|------------|
|
|
| `name` | `local/name` (default namespace is `local`) |
|
|
| `namespace/name` | Uses the specified namespace on the default server |
|
|
| `server:namespace/name` | Fully qualified — explicit server and namespace |
|
|
|
|
### Namespace Types
|
|
|
|
**`local/`** — Reserved namespace for machine-local entities. Stored in the local SQLite database. Fast iteration, no sharing, no server dependency. This is the default namespace when none is specified.
|
|
|
|
**`<username>/`** (e.g., `freemo/`, `jsmith/`) — Personal server namespace created when a user registers. Stored on the server, synced to the local machine when connected. Enables reusable entities across machines. Only the owning user can create or modify items.
|
|
|
|
**`<orgname>/`** (e.g., `cleverthis/`, `acme/`) — Organization namespace created when an organization is registered. Shared across team members. All entity types can be centrally managed under the org namespace.
|
|
|
|
**Built-in provider namespaces** (`openai/`, `anthropic/`, `google/`, etc.) — Reserved for built-in LLM actors. Automatically available when API keys are configured (via environment variables in local mode, or server-side keys in server mode). Cannot be used for custom actors.
|
|
|
|
### Server-Qualified Names
|
|
|
|
When connected to multiple servers, the server prefix disambiguates:
|
|
|
|
- `dev:freemo/code-coverage` — personal namespace on the `dev` server
|
|
- `prod:cleverthis/deploy-action` — org namespace on the `prod` server
|
|
|
|
### Resolution Rules
|
|
|
|
1. If the server prefix is omitted, the default server is assumed — unless the namespace is `local`, which always resolves locally.
|
|
2. If the namespace is omitted, `local` is used (configurable via `core.namespace`).
|
|
3. Names are stable identifiers; kebab-case is recommended.
|
|
|
|
### Entities Using This System
|
|
|
|
All of the following entity types follow the `namespace/name` convention: actors, tools, skills, resources, resource types, actions, projects, and plans.
|
|
|
|
## Constraints
|
|
|
|
- The `local/` namespace is reserved and must never be synced to a server.
|
|
- Built-in provider namespaces (`openai/`, `anthropic/`, `google/`, etc.) are reserved and must not be used for custom entity registration.
|
|
- Entity names within a namespace must be unique per entity type. The tuple `(namespace, entity_type, name)` is the uniqueness key.
|
|
- The `core.namespace` configuration key controls the default namespace prefix applied when creating entities without an explicit namespace.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- A single naming convention applies uniformly to all entity types, reducing cognitive overhead.
|
|
- Local-first development requires zero server configuration — `local/` is always available.
|
|
- Transitioning from local to shared usage is a namespace change, not a structural migration.
|
|
- Multi-server support is built into the naming scheme from the start, avoiding future retrofitting.
|
|
|
|
### Negative
|
|
- Entity names become longer when fully qualified, which may be verbose in CLI usage.
|
|
- Name resolution logic must be implemented in every subsystem that handles entity references.
|
|
- Namespace synchronization between client and server adds operational complexity.
|
|
|
|
### Risks
|
|
- Namespace collisions between user and organization names must be prevented at registration time.
|
|
- If the default namespace configuration is changed inadvertently, entity resolution may silently resolve to the wrong scope.
|
|
|
|
## Alternatives Considered
|
|
|
|
None — specification-driven requirement. The universal namespace system is a foundational design choice that enables the local-first-to-collaborative progression and multi-server deployment model prescribed by the specification.
|
|
|
|
## Compliance
|
|
|
|
- **Registration validation**: The `agents <entity> add` commands validate that the namespace is well-formed, not reserved (for custom entities), and that the user has write permissions to the target namespace.
|
|
- **Name format tests**: Unit tests verify that entity name parsing correctly handles all forms (`name`, `namespace/name`, `server:namespace/name`) and rejects malformed inputs.
|
|
- **Integration tests**: Multi-namespace scenarios (local + server, multiple servers) are exercised in integration test suites.
|
|
- **Code review**: New entity types must demonstrate they follow the namespace convention before merging.
|