diff --git a/api/group-management.mdx b/api/group-management.mdx index 0bfaa96..600a115 100644 --- a/api/group-management.mdx +++ b/api/group-management.mdx @@ -6,6 +6,10 @@ tag: "UPDATED" In v2, NanoClaw uses a new entity model that separates agent groups (workspaces) from messaging groups (platform chats). These are connected through wirings — many-to-many relationships stored in `messaging_group_agents`. + +For day-to-day inspection and modification of these entities, use the [`ncl` admin CLI](/features/admin-cli). It exposes `groups`, `messaging-groups`, `wirings`, `users`, `roles`, `members`, and `destinations` as resources with `list`/`get`/`create`/`update`/`delete` (or composite-key equivalents). + + ## Entity model ### Agent groups diff --git a/changelog/docs-updates.mdx b/changelog/docs-updates.mdx index 3da553f..419ca64 100644 --- a/changelog/docs-updates.mdx +++ b/changelog/docs-updates.mdx @@ -5,6 +5,16 @@ icon: "file-pen" rss: true --- + + Documented the `ncl` admin CLI introduced in upstream v2.0.45. + + ## New + - **`features/admin-cli.mdx`**: full reference for `ncl` — resource/verb table, host vs container transports (Unix socket on the host, session DB inside containers), `list` filtering and `--limit`, the approval flow for container-side writes (`approval-pending` → admin card → re-dispatch on approve → system message back to the agent), and example read/write commands. + - **`api/group-management.mdx`**: added a callout pointing readers to `ncl` for runtime inspection and modification of agent groups, messaging groups, wirings, users, roles, members, and destinations. + - **`changelog/index.mdx`**: v2.0.45 entry covering `ncl`, the approval flow for container-side writes, list filtering and pagination, the `nc` → `ncl` rename, and the v1 → v2 migration script. + - **Navigation**: `features/admin-cli` added to the Features group in `docs.json`. + + Phase A of the v2 documentation sprint — bringing the pages every new user lands on into alignment with the v2 rewrite. All claims verified directly against upstream source (`src/db/schema.ts`, `src/types.ts`, `src/config.ts`, `container/Dockerfile`, `src/delivery.ts`) rather than upstream `docs/` (which includes a stale `architecture.md` draft and a `db-session.md` that omits the `container_state` table). diff --git a/changelog/index.mdx b/changelog/index.mdx index 0608705..f844287 100644 --- a/changelog/index.mdx +++ b/changelog/index.mdx @@ -6,6 +6,15 @@ rss: true tag: "UPDATED" --- + + - **Admin CLI (`ncl`).** New command for querying and modifying NanoClaw's central DB — agent groups, messaging groups, wirings, users, roles, members, destinations, sessions, approvals, and dropped messages. Host transport runs over a Unix socket; container transport runs over the session DB. + - **Approval flow for container-side writes.** When an agent inside a container runs an `ncl` write command (`create`/`update`/`delete`/`grant`/`revoke`/`add`/`remove`), the dispatcher sends an approval card to an admin instead of executing inline. On approve, the original frame is re-dispatched on the host and the result is delivered back to the agent as a system message. + - **List filtering and pagination.** `ncl list` accepts column filters as flags (e.g. `--messaging-group-id mg_xyz`) and a `--limit` (default 200). Run `ncl help` for usage. See [Admin CLI](/features/admin-cli). + - **`nc` → `ncl` rename.** The CLI binary, socket path, container wrapper, and error prefixes were renamed from `nc` to `ncl`. Setup adds a `~/.local/bin/ncl` symlink and a pnpm script alias. + - **v1 → v2 migration.** Run `bash migrate-v2.sh` from a v2 checkout. The script merges `.env`, seeds the v2 DB from `registered_groups`, copies group folders (`CLAUDE.md` → `CLAUDE.local.md`), copies session data with conversation continuity, ports scheduled tasks, interactively installs channels, copies container skills, builds the agent container, and offers a service switchover. Hands off to Claude (`/migrate-from-v1`) for owner seeding, access policy, CLAUDE.md cleanup, and fork customization porting. + - **Migration fixes.** `1b-db` resolves Discord DMs as `discord:@me:` (previously skipped any v1 chat that wasn't a guild channel). `1c-groups` skips symlinks instead of following them. When `1b-db` reuses an auto-created `messaging_group` with no wired agents, its `unknown_sender_policy` is reconciled to the migration's `public` default. + + - Ground-up architectural rewrite with new entity model (users, roles, messaging groups, agent groups, wirings) - Two-database session model — `inbound.db` (host writes) and `outbound.db` (container writes) eliminate cross-mount SQLite contention diff --git a/docs.json b/docs.json index e84d181..a5f6cc0 100644 --- a/docs.json +++ b/docs.json @@ -116,6 +116,7 @@ "features/agent-swarms", "features/customization", "features/cli", + "features/admin-cli", "features/web-access", "features/voice-transcription", "features/image-vision", diff --git a/features/admin-cli.mdx b/features/admin-cli.mdx new file mode 100644 index 0000000..dbbee7a --- /dev/null +++ b/features/admin-cli.mdx @@ -0,0 +1,114 @@ +--- +title: Admin CLI (ncl) +description: Query and modify NanoClaw's central configuration — agent groups, messaging groups, wirings, users, roles, members, and more — from the host or from inside an agent container +keywords: ["ncl", "admin cli", "central db", "configuration", "approvals", "wirings", "roles"] +tag: "NEW" +--- + +## Overview + +`ncl` is the admin CLI for NanoClaw. It reads and writes the central database — the single source of truth for agent groups, messaging groups, wirings, users, roles, members, destinations, sessions, approvals, and dropped messages. + +It runs in two places with the same surface: + +- **On the host**, talking to the running NanoClaw process over a Unix socket. +- **Inside an agent container**, talking to the host through the session DB transport — so an agent can introspect or request changes without leaving its sandbox. + +The binary is `ncl` (renamed from `nc` in v2.0.45). On the host, setup symlinks it into `~/.local/bin`; inside containers it lives at `/usr/local/bin/ncl`. + +## Usage + +``` +ncl [] [--flags] +ncl help +ncl help +``` + +- Flags use `--hyphen-case` (e.g. `--agent-group-id`); they are mapped to `underscore_case` columns automatically. +- `list` accepts column filters (any non-auto column) and a `--limit` (default 200). +- ` help` prints all available fields, types, enums, and which fields are required or updatable. + +## Resources + +| Resource | Verbs | What it is | +|----------|-------|------------| +| `groups` | `list`, `get`, `create`, `update`, `delete` | Agent groups (workspace, personality, container config) | +| `messaging-groups` | `list`, `get`, `create`, `update`, `delete` | A single chat or channel on one platform | +| `wirings` | `list`, `get`, `create`, `update`, `delete` | Links a messaging group to an agent group (session mode, triggers) | +| `users` | `list`, `get`, `create`, `update` | Platform identities (`:`) | +| `roles` | `list`, `grant`, `revoke` | Owner / admin privileges (global or scoped to an agent group) | +| `members` | `list`, `add`, `remove` | Unprivileged access gate for an agent group | +| `destinations` | `list`, `add`, `remove` | Where an agent group can send messages | +| `sessions` | `list`, `get` | Active sessions (read-only) | +| `user-dms` | `list` | Cold-DM cache (read-only) | +| `dropped-messages` | `list` | Messages from unregistered senders (read-only) | +| `approvals` | `list`, `get` | Pending approval requests (read-only) | + +For composite-key resources (`roles`, `members`, `destinations`), use the custom verbs (`grant`/`revoke`, `add`/`remove`) instead of `create`/`delete`. + +## Access model + +- **Read commands** (`list`, `get`) are open from any caller. +- **Write commands** (`create`, `update`, `delete`, `grant`, `revoke`, `add`, `remove`) run inline when invoked from the host. When invoked from inside a container, they go through the [approval flow](#approval-flow). + +## Approval flow + +When an agent inside a container runs a write command, the dispatcher does **not** execute it inline. Instead, it requests approval from an admin and notifies the agent when the result is ready. + + + + For example: `ncl groups create --name "Research" --folder research`. + + + The command returns immediately with `approval-pending`. It has **not** been executed yet. + + + An admin or owner receives a notification (on the same channel when possible) showing exactly what the agent requested, with approve/reject options. Approvers are resolved from the `user_roles` table — preference order: scoped admins for the agent group, then global admins, then owners. + + + On approve, the original frame is re-dispatched on the host (`caller: 'host'`) and the result is delivered back to the agent as a system message. On reject, the agent is told the request was rejected. + + + +The agent doesn't need to poll or retry — the result arrives automatically. + + +`approval-pending` is not an error. Agents should treat it as the normal acknowledgement for any write command and wait for the system message with the final result. + + +## Examples + +```bash +# Read commands (no approval needed, work from host or container) +ncl groups list +ncl groups get abc123 +ncl wirings list --messaging-group-id mg_xyz +ncl wirings list --limit 50 +ncl roles list +ncl wirings help +``` + +```bash +# Write commands (inline on host, approval-gated from container) +ncl groups create --name "Research" --folder research +ncl groups update abc123 --name "Research v2" +ncl roles grant --user telegram:jane --role admin +ncl roles grant --user discord:bob --role admin --group abc123 +ncl members add --user-id telegram:jane --agent-group-id abc123 +ncl destinations add --agent-group-id abc123 --messaging-group-id mg_xyz +``` + +## Transports + +| Caller | Transport | Source | +|--------|-----------|--------| +| Host shell | Unix socket | `src/cli/socket-server.ts`, `src/cli/socket-client.ts` | +| Container agent | Session DB (request frame on outbound, response on inbound) | `container/agent-runner/src/cli/ncl.ts` | + +Both transports call the same dispatcher (`src/cli/dispatch.ts`); only the `CallerContext` differs. Generic CRUD is registered through `src/cli/crud.ts`, with per-resource definitions in `src/cli/resources/`. + +## Related + +- [Group management API](/api/group-management) — entity model behind the resources `ncl` exposes +- [Message routing](/api/message-routing) — how wirings tie messaging groups to agent groups +- [Security model](/advanced/security-model) — approval routing and role resolution