@nordbyte/nordrelay 0.2.1 → 0.3.1

package/.env.example

@@ -56,6 +56,12 @@ ENABLE_TELEGRAM_LOGIN=true
 ENABLE_TELEGRAM_REACTIONS=false
 TELEGRAM_RATE_LIMIT_MIN_INTERVAL_MS=80
 TELEGRAM_EDIT_MIN_INTERVAL_MS=1200
+TELEGRAM_TRANSPORT=polling
+TELEGRAM_WEBHOOK_URL=
+TELEGRAM_WEBHOOK_HOST=127.0.0.1
+TELEGRAM_WEBHOOK_PORT=8080
+TELEGRAM_WEBHOOK_PATH=/telegram/webhook
+TELEGRAM_WEBHOOK_SECRET=
 TELEGRAM_CLI_MIRROR_MODE=status
 TELEGRAM_CLI_MIRROR_MIN_UPDATE_MS=4000
 TELEGRAM_NOTIFY_MODE=minimal
@@ -69,6 +75,22 @@ ARTIFACT_IGNORE_DIRS=
 ARTIFACT_IGNORE_GLOBS=
 TELEGRAM_AUTO_SEND_ARTIFACTS=false
 
+# State and team controls. Use sqlite for a single-file state database when
+# better-sqlite3 is available; json keeps separate human-readable files.
+NORDRELAY_STATE_BACKEND=json
+NORDRELAY_AUDIT_MAX_EVENTS=1000
+NORDRELAY_SESSION_LOCK_TTL_MS=1800000
+NORDRELAY_VERSION_CACHE_TTL_MS=3600000
+
+# Local WebUI dashboard. Binding to 0.0.0.0 requires either token auth or
+# basic auth; startup fails without one of these credentials.
+NORDRELAY_DASHBOARD_HOST=127.0.0.1
+NORDRELAY_DASHBOARD_PORT=31878
+NORDRELAY_DASHBOARD_TOKEN=
+NORDRELAY_DASHBOARD_USER=
+NORDRELAY_DASHBOARD_PASSWORD=
+NORDRELAY_ENV_FILE=
+
 # Optional workspace guardrails. Leave WORKSPACE_ALLOWED_ROOTS empty to allow
 # all workspaces discovered from enabled agent state.
 WORKSPACE_ALLOWED_ROOTS=

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## v0.3.1 - 2026-05-12
+
+Commits since `v0.3.0`:
+
+- Move runtime home to .nordrelay.
+- Improve dashboard live status handling.
+- Separate dashboard contexts from Telegram sessions.
+- Expand dashboard controls and activity views.
+
+## v0.3.0 - 2026-05-12
+
+Commits since `v0.2.1`:
+
+- Prepare v0.3.0 release with copyable WebUI thread IDs and aligned session controls.
+- Improve dashboard usability and uploads.
+- Expand WebUI dashboard.
+- Keep dashboard server running.
+- Expand NordRelay platform features.
+- Hide missing timestamp marker in logs.
+- Show CLI paths directly in version output.
+- Add version freshness checks.
+- Render log messages as normal text.
+- Improve version and log display.
+- Improve logs and self-update behavior.

package/README.md

@@ -24,6 +24,7 @@ Session control:
 - `/handback` returns a ready-to-run CLI command for continuing in the native agent CLI.
 - `/retry` resends the last prompt for the current Telegram context.
 - `/queue`, inline run/top/up/down/cancel buttons, `/cancel <queue-id>`, and `/clearqueue` manage queued prompts for a busy Telegram context.
+- `/queue later <minutes> <prompt>` schedules a prompt for later execution, and `/queue inspect <queue-id>` shows full queue metadata.
 - `/abort`, `/stop`, and the inline Abort button cancel the active agent turn.
 - Busy prompts are queued per Telegram context instead of being dropped.
 - If the attached thread is currently active in the local Codex CLI, Telegram prompts are queued until that CLI task finishes.
@@ -36,6 +37,15 @@ Session control:
 - `/tasks` and `/progress` show the current turn status, queue length, active tool, elapsed time, and last error.
 - `/activity` shows a compact timeline of recent rollout events for the active thread, with filters and export.
 - `/diagnostics` reports redacted runtime, config, role, Telegram rate-limit, mirror, voice, session, queue, and progress details for admins.
+- `/lock`, `/unlock`, and `/locks` provide a team write-lock for shared sessions so one user can operate while others watch.
+- `/audit` shows recent prompt, queue, lock, and command audit events for admins.
+
+Adapter architecture:
+
+- Telegram is implemented as the first channel adapter with text, typing, streaming edits, inline buttons, files, photos, voice, topics, and webhook capability metadata.
+- `/channels` shows available and planned messaging adapters for Discord, WhatsApp, Slack, and Matrix.
+- Codex and Pi are implemented as agent adapters, with descriptors for future Claude Code, OpenClaw, and Hermes support.
+- `/agents` shows available/planned agent adapters and whether Codex/Pi are enabled.
 
 Codex runtime:
 
@@ -95,6 +105,7 @@ Telegram output:
 - Image artifacts are sent with Telegram previews; large multi-file outputs are bundled into one ZIP when possible.
 - `/artifacts` lists recent generated files and can resend the latest or a specific artifact turn.
 - `/artifacts` includes inline actions to resend, ZIP, or delete artifact turns.
+- `/artifacts images`, `/artifacts docs`, `/artifacts search <text>`, and `/artifacts delete <turn-id>` filter, find, and clean up artifacts from Telegram.
 - Old artifact and inbox turn directories are pruned automatically with configurable retention.
 - Optional Telegram message reactions can acknowledge work start and completion with `ENABLE_TELEGRAM_REACTIONS=true`.
 
@@ -120,24 +131,43 @@ Operations:
 - Plugin command/skill starts, stops, restarts, and inspects the connector process.
 - Manual process commands support `start`, `stop`, `restart`, `status`, and `foreground`.
 - Telegram admin commands support `/logs`, `/diagnostics`, `/restart`, and `/update`.
-- `/update` pulls changes, installs dependencies, runs check, tests, and build, and restarts only after all steps pass.
-- Logs can be emitted as plain text or JSON records with `CONNECTOR_LOG_FORMAT`.
+- `/update` detects the install type: npm installs update with `npm install -g @nordbyte/nordrelay@latest`; source checkouts pull `origin/main`, install dependencies, run check, tests, and build, then restart.
+- `/logs` renders redacted connector and update logs with local-time timestamps, levels, file path, last-modified time, and highlighted warnings/errors.
+- Logs can be emitted as timestamped plain text or JSON records with `CONNECTOR_LOG_FORMAT`.
 - Telegram sends/edits/documents are routed through a rate-limit queue that honors Telegram retry-after responses.
 - Context metadata, queues, and preferences are written atomically with backup recovery.
-- Runtime state and logs are written under `~/.codex/nordrelay/`.
+- Context metadata, queues, preferences, audit events, and locks can use JSON files or the optional SQLite state backend with `NORDRELAY_STATE_BACKEND=sqlite`.
+- Runtime config, state, and logs are written under `~/.nordrelay/`.
+- `nordrelay init` creates a private runtime config, `nordrelay doctor` validates host prerequisites, and `nordrelay web` starts a full local WebUI dashboard.
+- The WebUI has responsive header/sidebar/footer navigation, live chat streaming, session controls, queue/artifact/log/diagnostic views, and settings management.
+- The WebUI supports light and dark themes, tabbed settings groups, paginated session browsing, and chat uploads for images, documents, and audio transcription.
+- The WebUI exposes REST and SSE endpoints for chat streaming, sessions, settings, queue, artifacts, logs, health, and diagnostics.
+- Binding the dashboard to `0.0.0.0` is refused unless `NORDRELAY_DASHBOARD_TOKEN` or `NORDRELAY_DASHBOARD_USER` plus `NORDRELAY_DASHBOARD_PASSWORD` is configured.
+- Telegram can run with long polling or an HTTP webhook via `TELEGRAM_TRANSPORT=webhook`.
+- Version freshness checks are cached with `NORDRELAY_VERSION_CACHE_TTL_MS` to keep `/version` responsive.
+- CI includes typecheck, tests, package dry run, npm audit, and a separate secret-scan workflow.
 - `npm run dev`, `npm run build`, `npm run check`, `npm test`, `npm start`, `npm stop`, and `npm run status` are available.
 - Dockerfile and `docker-compose.yml` are included for containerized operation.
 - A `launchd/start.sh` helper is included for host-managed startup.
 
 ## First Run Setup
 
-Install the published package:
+Recommended npm setup:
 
 ```bash
 npm install -g @nordbyte/nordrelay
+nordrelay init
+nordrelay doctor
+nordrelay start
 ```
 
-For package installs, put runtime configuration in a directory-local `.env` before running `nordrelay`, or in `~/.codex/nordrelay/nordrelay.env`.
+npm is the fastest install path and is the recommended default for normal use. `nordrelay init` writes the private runtime config to `~/.nordrelay/nordrelay.env`.
+
+Non-interactive setup is also supported:
+
+```bash
+nordrelay init --token 123456789:replace-me --admin-id 123456789
+```
 
 Source checkout setup:
 
@@ -146,7 +176,9 @@ Install dependencies and build the runtime:
 ```bash
 npm install
 npm run build
-cp .env.example .env
+mkdir -p ~/.nordrelay
+cp .env.example ~/.nordrelay/nordrelay.env
+chmod 600 ~/.nordrelay/nordrelay.env
 ```
 
 Create the Telegram bot:
@@ -154,11 +186,11 @@ Create the Telegram bot:
 1. Open Telegram and talk to `@BotFather`.
 2. Run `/newbot`.
 3. Choose a display name and bot username.
-4. Copy the bot token into `TELEGRAM_BOT_TOKEN` in `.env`.
+4. Copy the bot token into `TELEGRAM_BOT_TOKEN` in `~/.nordrelay/nordrelay.env`.
 5. Find your Telegram user id with a trusted id helper bot, for example `@userinfobot`, or from Telegram API tooling.
 6. Put your user id into `TELEGRAM_ADMIN_USER_IDS`.
 
-Minimal private-bot `.env`:
+Minimal private-bot `~/.nordrelay/nordrelay.env`:
 
 ```dotenv
 TELEGRAM_BOT_TOKEN=123456789:replace-me
@@ -187,7 +219,7 @@ Codex authentication:
 Pi setup:
 
 - Install Pi from https://pi.dev/ and confirm `pi --help` works on the host.
-- Set `NORDRELAY_PI_ENABLED=true` in `.env`.
+- Set `NORDRELAY_PI_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
 - Keep `NORDRELAY_DEFAULT_AGENT=codex` to start chats in Codex, or set `NORDRELAY_DEFAULT_AGENT=pi` to start chats in Pi.
 - Optional: set `PI_SESSION_DIR` if your Pi sessions are not stored in `~/.pi/agent/sessions/`.
 - Optional: set `PI_DEFAULT_MODEL=openai-codex/gpt-5.5` and `PI_DEFAULT_THINKING=medium`.
@@ -219,11 +251,14 @@ The old unnamespaced `/remote` command is no longer required and current Codex T
 Manual process commands:
 
 ```bash
+nordrelay init
+nordrelay doctor
 nordrelay start
 nordrelay status
 nordrelay restart
 nordrelay stop
 nordrelay foreground
+nordrelay web
 ```
 
 Source checkout process commands:
@@ -234,6 +269,8 @@ node plugins/nordrelay/scripts/nordrelay.mjs status
 node plugins/nordrelay/scripts/nordrelay.mjs restart
 node plugins/nordrelay/scripts/nordrelay.mjs stop
 node plugins/nordrelay/scripts/nordrelay.mjs foreground
+node plugins/nordrelay/scripts/nordrelay.mjs doctor
+node plugins/nordrelay/scripts/nordrelay.mjs web
 ```
 
 NPM shortcuts:
@@ -247,15 +284,76 @@ npm run foreground
 
 Runtime files:
 
-- PID file: `~/.codex/nordrelay/nordrelay.pid`
-- State file: `~/.codex/nordrelay/state.json`
-- Log file: `~/.codex/nordrelay/nordrelay.log`
+- PID file: `~/.nordrelay/nordrelay.pid`
+- State file: `~/.nordrelay/state.json`
+- Log file: `~/.nordrelay/nordrelay.log`
 - Home override: `NORDRELAY_HOME=/custom/path`
+- Local dashboard: `nordrelay web --host 127.0.0.1 --port 31878`
+
+## WebUI Dashboard
+
+Start the local WebUI:
+
+```bash
+nordrelay web
+```
+
+Open:
+
+```text
+http://127.0.0.1:31878/
+```
+
+The dashboard is a second NordRelay client next to Telegram. It can:
+
+- Start a new Codex or Pi session.
+- Start a new session from a modal with agent, workspace, model, reasoning/thinking, fast mode, and launch-profile choices.
+- Switch or attach existing sessions, and copy thread IDs from the session list.
+- Send prompts and receive streamed text/tool/plan updates through Server-Sent Events.
+- Upload images, documents, and audio files from the chat composer. Images are passed as image inputs, documents are staged for the agent, and audio is transcribed through the configured voice backend.
+- Keep a persistent per-thread WebUI chat history across page reloads.
+- Control the active session model, reasoning/thinking, fast mode, and launch profile directly from the chat view.
+- Abort turns, hand sessions back to the native CLI, and inspect the active session.
+- Manage queued prompts with pause/resume, run, cancel, reorder buttons, and drag-and-drop prioritization.
+- Browse, preview, download, ZIP, and delete artifacts.
+- Inspect the activity timeline for WebUI and mirrored CLI turns.
+- Edit all supported runtime settings from tabbed Settings groups with option selects, validation feedback, and restart actions.
+- View filtered logs, structured diagnostics, enabled channels, and agent adapters.
+
+Dashboard API endpoints are served under `/api/*`. Streaming uses `GET /api/events`.
+
+Dashboard auth:
+
+```dotenv
+NORDRELAY_DASHBOARD_HOST=127.0.0.1
+NORDRELAY_DASHBOARD_PORT=31878
+NORDRELAY_DASHBOARD_TOKEN=replace-with-random-token
+# or:
+NORDRELAY_DASHBOARD_USER=admin
+NORDRELAY_DASHBOARD_PASSWORD=replace-with-random-password
+```
+
+When `NORDRELAY_DASHBOARD_HOST=0.0.0.0`, NordRelay refuses to start the dashboard unless token or basic auth is configured. Login cookies use `SameSite=Strict`, and every dashboard route, API endpoint, SSE stream, artifact download, and health endpoint requires the same auth.
+
+Webhook mode:
+
+```dotenv
+TELEGRAM_TRANSPORT=webhook
+TELEGRAM_WEBHOOK_URL=https://relay.example
+TELEGRAM_WEBHOOK_HOST=127.0.0.1
+TELEGRAM_WEBHOOK_PORT=8080
+TELEGRAM_WEBHOOK_PATH=/telegram/webhook
+TELEGRAM_WEBHOOK_SECRET=replace-with-random-secret
+```
+
+Run NordRelay behind your reverse proxy so the public URL forwards to `http://127.0.0.1:8080/telegram/webhook`. `GET /healthz` returns a simple health check.
 
 ## Telegram Commands
 
 - `/start` shows welcome text and the selected launch profile.
 - `/help` shows the grouped command reference.
+- `/channels` shows available and planned messaging adapters.
+- `/agents` shows available and planned coding-agent adapters.
 - `/agent` selects the active agent for this Telegram context.
 - `/new` starts a new thread. If the selected agent knows multiple workspaces, Telegram shows a workspace picker.
 - `/session` shows current thread details.
@@ -272,13 +370,19 @@ Runtime files:
 - `/queue` shows queued prompts for this Telegram context with inline run/top/up/down/cancel buttons.
 - `/queue pause` pauses automatic queued prompt execution.
 - `/queue resume` resumes automatic queued prompt execution.
+- `/queue later <minutes> <prompt>` schedules a prompt for later execution.
+- `/queue inspect <queue-id>` shows one queued prompt with created time, schedule time, attempts, and last error.
 - `/queue move <queue-id> top|up|down` changes queued prompt priority.
 - `/queue run <queue-id>` resumes the queue and runs that prompt next when the session is idle.
 - Queued prompt replies include a cancel button while the prompt is still waiting.
 - `/cancel <queue-id>` removes one queued prompt; the queue id is the short code shown in messages such as `Queued prompt 332kmt`.
 - `/clearqueue` clears queued prompts for this Telegram context.
 - `/activity [all|tools|errors|user|agent|tasks] [limit] [since 1h] [export]` shows or exports rollout activity for the active thread.
-- `/artifacts [latest|zip latest|turn-id]` lists or resends generated artifacts for the current workspace.
+- `/audit [limit]` shows recent audit events. Admin only.
+- `/lock` locks writes for this Telegram session to the current user.
+- `/unlock` releases the current session write lock.
+- `/locks` lists active write locks.
+- `/artifacts [latest|zip latest|turn-id|images|docs|search <text>|delete <turn-id>]` lists, filters, resends, zips, searches, or deletes generated artifacts for the current workspace.
 - `/workspaces` lists workspaces known to the selected agent and allowed by the workspace policy.
 - `/abort` cancels the current operation.
 - `/stop` is an alias for `/abort`.
@@ -300,11 +404,13 @@ Runtime files:
 - `/tasks` or `/progress` reports the current turn and queue progress.
 - `/status` reports connector runtime status.
 - `/health` reports runtime health, auth, PIDs, Codex CLI, Pi CLI, and state DB.
-- `/version` reports connector, Codex CLI, and Pi CLI version context.
-- `/logs [lines]` shows a redacted connector log tail. Admin only.
+- `/version` reports connector, Codex CLI, and Pi CLI paths plus installed/latest NordRelay, Codex, and Pi versions with status icons.
+- `/logs [lines]` shows a redacted, timestamped connector log tail. Admin only.
+- `/logs update [lines]` shows the self-update log. Admin only.
+- `/logs all [lines]` shows connector and self-update logs together. Admin only.
 - `/diagnostics` shows redacted connector diagnostics. Admin only.
 - `/restart` restarts the connector process. Admin only.
-- `/update` pulls `origin/main`, installs dependencies, checks, tests, builds, and restarts only on success. Admin only.
+- `/update` updates through npm or git depending on the detected install type, then restarts only on success. Admin only.
 
 ## Command Examples
 
@@ -422,6 +528,8 @@ Artifacts:
 - When more than five artifacts are sent, the connector tries to send one ZIP bundle instead of many separate files.
 - Use `/artifacts` to list recent artifact turns with inline Send/ZIP/Delete actions.
 - Use `/artifacts latest`, `/artifacts zip latest`, or `/artifacts <turn-id>` from text commands.
+- Use `/artifacts images`, `/artifacts docs`, or `/artifacts search <text>` to narrow large artifact histories.
+- Use `/artifacts delete <turn-id>` to delete an artifact turn without opening the inline confirmation flow.
 - Telegram file delivery is capped at the configured `MAX_FILE_SIZE` per artifact or ZIP bundle.
 - Old turn and inbox directories are pruned automatically to keep workspace state compact.
 
@@ -475,6 +583,12 @@ Telegram:
 - `TELEGRAM_ROLE_POLICIES_JSON`: optional JSON object mapping roles to permissions. Permissions are `inspect`, `sessions`, `prompt`, `files`, `settings`, `auth`, and `admin`.
 - `TELEGRAM_RATE_LIMIT_MIN_INTERVAL_MS`: minimum interval for normal Telegram API sends. Defaults to `80`.
 - `TELEGRAM_EDIT_MIN_INTERVAL_MS`: minimum interval for Telegram message edits. Defaults to `1200`.
+- `TELEGRAM_TRANSPORT`: `polling` or `webhook`. Defaults to `polling`.
+- `TELEGRAM_WEBHOOK_URL`: public base URL for webhook mode, for example `https://relay.example`.
+- `TELEGRAM_WEBHOOK_HOST`: local bind host for webhook mode. Defaults to `127.0.0.1`.
+- `TELEGRAM_WEBHOOK_PORT`: local bind port for webhook mode. Defaults to `8080`.
+- `TELEGRAM_WEBHOOK_PATH`: webhook request path. Defaults to `/telegram/webhook`.
+- `TELEGRAM_WEBHOOK_SECRET`: optional Telegram webhook secret token.
 - `TELEGRAM_CLI_MIRROR_MODE`: default CLI mirror mode: `off`, `status`, `final`, or `full`. Defaults to `status`.
 - `TELEGRAM_CLI_MIRROR_MIN_UPDATE_MS`: minimum interval for mirrored CLI status edits. Defaults to `4000`.
 - `TELEGRAM_NOTIFY_MODE`: default notification mode: `off`, `minimal`, or `all`. Defaults to `minimal`.
@@ -492,6 +606,19 @@ Agent selection:
 - `NORDRELAY_CODEX_ENABLED`: enables Codex contexts. Defaults to `true`.
 - `NORDRELAY_PI_ENABLED`: enables Pi contexts. Defaults to `false`.
 - `NORDRELAY_DEFAULT_AGENT`: `codex` or `pi`, used for new Telegram contexts. Defaults to the first enabled agent.
+- `NORDRELAY_STATE_BACKEND`: `json` or `sqlite`. JSON is the default; SQLite requires `better-sqlite3`.
+- `NORDRELAY_AUDIT_MAX_EVENTS`: maximum audit events retained. Defaults to `1000`.
+- `NORDRELAY_SESSION_LOCK_TTL_MS`: session write-lock TTL. Defaults to `1800000`.
+- `NORDRELAY_VERSION_CACHE_TTL_MS`: npm version freshness cache TTL. Defaults to `3600000`; set `0` to disable.
+
+Dashboard:
+
+- `NORDRELAY_DASHBOARD_HOST`: dashboard bind host. Defaults to `127.0.0.1`.
+- `NORDRELAY_DASHBOARD_PORT`: dashboard bind port. Defaults to `31878`.
+- `NORDRELAY_DASHBOARD_TOKEN`: optional dashboard bearer/login token. Required when binding to `0.0.0.0` unless basic auth is configured.
+- `NORDRELAY_DASHBOARD_USER`: optional dashboard basic-auth user.
+- `NORDRELAY_DASHBOARD_PASSWORD`: optional dashboard basic-auth password. Required with `NORDRELAY_DASHBOARD_USER`.
+- `NORDRELAY_ENV_FILE`: optional explicit env-file path used by the wrapper and edited by the dashboard settings page. Defaults to `~/.nordrelay/nordrelay.env`.
 
 Codex:
 
@@ -550,8 +677,9 @@ Auth and voice:
 
 NordRelay wrapper:
 
-- `NORDRELAY_HOME`: state/log directory override. Defaults to `~/.codex/nordrelay`.
+- `NORDRELAY_HOME`: config/state/log directory override. Defaults to `~/.nordrelay`.
 - `NORDRELAY_SOURCE_ROOT`: runtime source root override. Useful when the plugin is launched from Codex cache.
+- `NORDRELAY_UPDATE_METHOD`: optional `auto`, `npm`, or `git` self-update method override. Auto uses git when the runtime root has a `.git` directory and npm otherwise.
 - `NORDRELAY_KEEP_PENDING_UPDATES`: set true to avoid dropping pending Telegram updates on start.
 - `NORDRELAY_FORWARD_TOOL_OUTPUT`: backward-compatible alias that sets `TOOL_VERBOSITY=all` when `TOOL_VERBOSITY` is unset.
 - `NORDRELAY_STATE_FILE`: internal state-file path passed by the wrapper.
@@ -597,7 +725,7 @@ Unsafe profiles are intentionally gated. Telegram asks for confirmation before a
 - Do not leave `TELEGRAM_ALLOW_ANY_CHAT=true` enabled after setup.
 - Treat `danger-full-access` as equivalent to shell access on the host.
 - Treat uploaded files as untrusted input. They are staged inside the active workspace so the selected sandbox policy still matters.
-- Keep `CODEX_API_KEY` and `OPENAI_API_KEY` in `.env` or host secret management; `.env` is gitignored.
+- Keep `CODEX_API_KEY` and `OPENAI_API_KEY` in `~/.nordrelay/nordrelay.env` or host secret management.
 - In group chats, remember that any allowed user can prompt Codex in that chat context.
 - Use `TOOL_VERBOSITY=summary` or `errors-only` when command output may include sensitive data.
 - Review and unsafe launch profiles add a Telegram approve/deny gate before each turn starts.
@@ -655,7 +783,7 @@ Voice not working:
 
 - Run `/voice` to list available backends.
 - Install `ffmpeg` and `faster-whisper` on Linux, install `parakeet-coreml` on macOS Apple Silicon, or set `OPENAI_API_KEY`.
-- Check `~/.codex/nordrelay/nordrelay.log` for transcription errors.
+- Check `~/.nordrelay/nordrelay.log` for transcription errors.
 
 Files not returned:
 

package/dist/access-control.js

@@ -13,10 +13,13 @@ const COMMAND_PERMISSIONS = new Map([
     ["status", "inspect"],
     ["health", "inspect"],
     ["version", "inspect"],
+    ["channels", "inspect"],
+    ["agents", "inspect"],
     ["diagnostics", "admin"],
     ["tasks", "inspect"],
     ["progress", "inspect"],
     ["activity", "inspect"],
+    ["audit", "admin"],
     ["mirror", "settings"],
     ["notify", "settings"],
     ["workspaces", "sessions"],
@@ -32,6 +35,9 @@ const COMMAND_PERMISSIONS = new Map([
     ["handback", "sessions"],
     ["new", "sessions"],
     ["sync", "sessions"],
+    ["lock", "sessions"],
+    ["unlock", "sessions"],
+    ["locks", "sessions"],
     ["queue", "inspect"],
     ["cancel", "prompt"],
     ["clearqueue", "prompt"],

package/dist/agent-adapter.js

@@ -0,0 +1,60 @@
+import { CODEX_AGENT_CAPABILITIES, PI_AGENT_CAPABILITIES, } from "./agent.js";
+export const BUILTIN_AGENT_ADAPTERS = [
+    {
+        id: "codex",
+        label: "Codex",
+        status: "available",
+        capabilities: CODEX_AGENT_CAPABILITIES,
+        envFlag: "NORDRELAY_CODEX_ENABLED",
+    },
+    {
+        id: "pi",
+        label: "Pi",
+        status: "available",
+        capabilities: PI_AGENT_CAPABILITIES,
+        envFlag: "NORDRELAY_PI_ENABLED",
+    },
+    {
+        id: "claude-code",
+        label: "Claude Code",
+        status: "planned",
+        capabilities: plannedCapabilities(),
+        notes: "Use this descriptor as the target contract for a future Claude Code session service.",
+    },
+    {
+        id: "openclaw",
+        label: "OpenClaw",
+        status: "planned",
+        capabilities: plannedCapabilities(),
+    },
+    {
+        id: "hermes",
+        label: "Hermes",
+        status: "planned",
+        capabilities: plannedCapabilities(),
+    },
+];
+export function listAgentAdapterDescriptors() {
+    return BUILTIN_AGENT_ADAPTERS.map((descriptor) => ({
+        ...descriptor,
+        capabilities: { ...descriptor.capabilities },
+    }));
+}
+function plannedCapabilities() {
+    return {
+        launchProfiles: false,
+        fastMode: false,
+        externalActivity: false,
+        cliMirror: false,
+        activityLog: false,
+        auth: false,
+        login: false,
+        logout: false,
+        usageLimits: false,
+        workspaces: true,
+        attachments: true,
+        modelSelection: true,
+        reasoningSelection: true,
+        handback: true,
+    };
+}

package/dist/audit-log.js

@@ -0,0 +1,54 @@
+import { randomUUID } from "node:crypto";
+import { createDocumentStore } from "./state-backend.js";
+export class AuditLogStore {
+    store;
+    maxEvents;
+    constructor(workspace, backend = "json", maxEvents = 1000) {
+        this.store = createDocumentStore({
+            workspace,
+            fileName: "audit.json",
+            sqliteKey: "audit",
+            backend,
+        });
+        this.maxEvents = maxEvents;
+    }
+    append(event) {
+        const payload = this.readPayload();
+        const next = {
+            id: randomUUID().replace(/-/g, "").slice(0, 12),
+            timestamp: new Date().toISOString(),
+            channelId: "telegram",
+            ...event,
+        };
+        payload.events.push(next);
+        if (payload.events.length > this.maxEvents) {
+            payload.events.splice(0, payload.events.length - this.maxEvents);
+        }
+        this.store.write(payload);
+        return next;
+    }
+    list(limit = 20) {
+        return this.readPayload().events.slice(-Math.max(1, Math.min(200, limit))).reverse();
+    }
+    readPayload() {
+        const payload = this.store.read();
+        if (!payload || payload.version !== 1 || !Array.isArray(payload.events)) {
+            return { version: 1, events: [] };
+        }
+        return {
+            version: 1,
+            events: payload.events.filter(isAuditEvent),
+        };
+    }
+}
+function isAuditEvent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.id === "string" &&
+        typeof candidate.timestamp === "string" &&
+        typeof candidate.action === "string" &&
+        typeof candidate.status === "string" &&
+        typeof candidate.contextKey === "string";
+}

package/dist/bot-preferences.js

@@ -1,10 +1,14 @@
-import path from "node:path";
-import { readJsonFileWithBackup, writeJsonFileAtomic } from "./persistence.js";
+import { createDocumentStore } from "./state-backend.js";
 export class BotPreferencesStore {
-    persistPath;
+    store;
     contexts = new Map();
-    constructor(workspace) {
-        this.persistPath = path.join(workspace, ".nordrelay", "preferences.json");
+    constructor(workspace, backend = "json") {
+        this.store = createDocumentStore({
+            workspace,
+            fileName: "preferences.json",
+            sqliteKey: "preferences",
+            backend,
+        });
         this.load();
     }
     get(contextKey) {
@@ -29,14 +33,14 @@ export class BotPreferencesStore {
             version: 1,
             contexts: Object.fromEntries(this.contexts.entries()),
         };
-        writeJsonFileAtomic(this.persistPath, payload);
+        this.store.write(payload);
     }
     load() {
-        const result = readJsonFileWithBackup(this.persistPath);
-        if (!result.value?.contexts || typeof result.value.contexts !== "object") {
+        const payload = this.store.read();
+        if (!payload?.contexts || typeof payload.contexts !== "object") {
             return;
         }
-        for (const [contextKey, rawPreferences] of Object.entries(result.value.contexts)) {
+        for (const [contextKey, rawPreferences] of Object.entries(payload.contexts)) {
             const preferences = normalizePreferences(rawPreferences);
             if (preferences) {
                 this.contexts.set(contextKey, preferences);

package/dist/bot-ui.js

@@ -51,12 +51,15 @@ export function renderHelpMessage() {
             commands: [
                 ["/start", "Welcome & status"],
                 ["/help", "This reference"],
+                ["/channels", "Messaging adapter status"],
+                ["/agents", "Agent adapter status"],
                 ["/voice", "Voice transcription status"],
                 ["/status", "Connector runtime status"],
                 ["/health", "Connector health report"],
                 ["/version", "Connector version"],
                 ["/tasks", "Current turn progress"],
                 ["/activity", "Thread activity timeline"],
+                ["/audit", "Recent audit events"],
             ],
         },
         {
@@ -64,6 +67,9 @@ export function renderHelpMessage() {
             commands: [
                 ["/logs", "Show connector log tail"],
                 ["/diagnostics", "Connector diagnostics"],
+                ["/lock", "Lock session writes to you"],
+                ["/unlock", "Release session write lock"],
+                ["/locks", "List active write locks"],
                 ["/restart", "Restart connector"],
                 ["/update", "Pull, build, and restart"],
             ],