dguiducci
4f10528368
Nightly Build / build (push) Successful in 7m40s
The first AgentScope::PerSubject system agent, and the reason that scope exists. Once a night, for each person with a supervision edge, it reads every message that person and the assistant exchanged since the previous review — across all their conversations — and writes one report for the people who supervise them. Schema (all registry except reports): - supervision(subject_user_id, supervisor_user_id): the generic §0.1 edge, answering both 'whom does a background agent look at' and 'who may read what it produced', with real FKs so deleting a user cascades both ways - system_agent_coverage(agent_id, subject_user_id, covered_through): the per-subject watermark that makes 'everything since last time' a window — neither system_agent_runs (history for humans) nor system_agent_state (advances before the work), and advanced only on a completed pass so a crash re-covers instead of skipping - reports (owner schema, the second two-homes table after memory_docs): instance rows land in system.db, deliberately cleartext to the box owner, who is the intended reader (§2); the subject cannot see them structurally The pass reads the subject's database inside a supervisor's runtime, so the ephemeral session and run row land in the watcher's file; iteration is over subjects, so two parents watching one child get one review; and the subject need not be logged in when their space is unencrypted — via the new UserManager::open_unencrypted, which refuses an encrypted user outright (no key to be had) and never registers the pool as unlocked. The agent declares the new AgentMeta flag allow_tools: false, so its turn gets an empty tool registry — nothing for a prompt injection in the transcript to call — and produces its report as its final assistant message, read back from chat_history and parsed (NOTHING_TO_REPORT sentinel, no row on quiet days). chat_history::conversation_window is the transcript query; its four filters (non-ephemeral, depth 0, non-synthetic, non-empty) each guard a specific way the review would otherwise be wrong, and tool calls are absent by construction. Cadence is Run at (hour) rather than Interval — 4am local by default — with due-ness answered inside has_work against the coverage watermark, so a machine off for three days covers the whole stretch in one pass. Reports announce ReportCreated on the system bus (no subscriber yet). run_ephemeral_turn gains a per-pass system_substitutions map, which the review uses to hand the model the subject's profile under __SUBJECT_PROFILE__ — the system-context substitutions describe the session owner, the wrong person here. docs/system-agents.md gains the conversation review section; CLAUDE.md documents the scope, the tables and the tool-less design.
42 lines
4.5 KiB
Markdown
42 lines
4.5 KiB
Markdown
# Documentation index
|
|
|
|
This folder is written for **you, the assistant**, not for the human directly. It is mounted read-only at `~/docs/` in your workspace. Read it when a user asks how the software itself works, wants help configuring something, or asks what's possible — then explain it in your own words, adapted to that person (their technical level, their language, their actual goal). Don't just paste these files back at them.
|
|
|
|
Keep answers grounded in what's actually enabled and configured for this instance — check with the relevant tool (e.g. list installed/enabled plugins) rather than assuming everything described here is turned on. A feature documented here may not be enabled on this particular instance.
|
|
|
|
This index will grow over time. Right now it covers memory, projects, system agents, access grants and plugins; more sections (agents, connectors, security groups, shared folders…) will be added later.
|
|
|
|
## Features
|
|
|
|
| Document | What it covers |
|
|
| --- | --- |
|
|
| [memory.md](memory.md) | Private and shared memory: what goes where, the indexes and history log, why some shared facts can't be changed on request |
|
|
| [projects.md](projects.md) | Projects: shared folders with their own assistant chat, a live file explorer, and member sharing |
|
|
| [system-agents.md](system-agents.md) | Background agents that run on a schedule (event triage, the two memory lints, the nightly conversation review of a supervised account): what they watch, why they only ever report, why a run can be skipped, and their settings |
|
|
| [settings.md](settings.md) | The admin's Config page: interface language, the compaction model picker, debug mode |
|
|
| [access.md](access.md) | Who can use which plugin or connector: the open default, removing access per person, and the role switch that keeps children out of it |
|
|
|
|
## Plugins
|
|
|
|
Plugins are optional add-ons an admin can enable and configure — extra voices, extra ways to reach the assistant (Telegram, a phone app), image generation, long-term memory, remote access, and so on. Each has its own document in [`plugins/`](plugins/):
|
|
|
|
| Document | What it adds |
|
|
| --- | --- |
|
|
| [plugins/comfyui.md](plugins/comfyui.md) | Local image generation via a self-hosted ComfyUI server |
|
|
| [plugins/elevenlabs.md](plugins/elevenlabs.md) | Cloud text-to-speech and transcription (ElevenLabs) |
|
|
| [plugins/whisper_local.md](plugins/whisper_local.md) | Local, private speech-to-text (no cloud, no API key) |
|
|
| [plugins/kokoro_tts.md](plugins/kokoro_tts.md) | Local, lightweight text-to-speech (CPU-only, no API key) |
|
|
| [plugins/orpheus_tts_3b.md](plugins/orpheus_tts_3b.md) | Local, expressive text-to-speech with emotion tags (needs a GPU) |
|
|
| [plugins/honcho.md](plugins/honcho.md) | Long-term cross-session memory via an external Honcho server (opt-in per user) |
|
|
| [plugins/telegram.md](plugins/telegram.md) | Chat with the assistant from Telegram |
|
|
| [plugins/mobile-connector.md](plugins/mobile-connector.md) | Companion mobile app: Inbox notifications + remote access, end-to-end encrypted |
|
|
| [plugins/remote_connectivity.md](plugins/remote_connectivity.md) | Reach the web app remotely over a Tailscale mesh network |
|
|
|
|
General plugin mechanics that apply to all of them:
|
|
|
|
- An admin enables/disables and configures each plugin from the **Plugins** page (sidebar → Plugins, admin-only): one card per plugin, an enable toggle, and a **Configure** button opening its settings form.
|
|
- Enabling a plugin hands it to everyone straight away — except to roles that opt out of that (the Children role does). The admin then *removes* it from whoever should not have it, rather than granting it person by person. Full details in [access.md](access.md). (Mobile Connector is the one exception to the whole grant model: access there is the device-pairing itself, not a grant list.)
|
|
- Access is changed **per person, from that person's own page**: sidebar → Users → click the user → the **Plugins** section, right below their Connectors. So "what may this person use?" is answered in one place, for plugins and connectors together. (The plugin's own page shows the reverse view — who currently holds it — but read-only.) Admins can use every enabled plugin without being granted anything.
|
|
- A plugin with **per-user** settings (e.g. Telegram's pairing code, Honcho's memory opt-in) gives each granted user its own dedicated **sidebar page** to manage them — separate from the admin's instance-wide config.
|
|
- A plugin can add tools the assistant calls directly (e.g. `set_secret`, `telegram_pairing`), a dedicated sidebar page, or both.
|