dguiducci/Skald-Circle
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat: conversation review — a nightly report on a supervised person's conversations
Nightly Build / build (push) Successful in 7m40s
Details

Browse Source 
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.
This commit is contained in:
dguiducci
2026-08-02 20:30:27 +01:00
parent e6818408cb
commit 4f10528368
19 changed files with 2394 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+19 -3
View File
@@ -28,7 +28,7 @@ Three global broadcast buses — **never add a fourth without checking these fir
| Bus | Cap | Events | File |
|-----|-----|--------|------|
| `ChatEventBus` | 256 | user message, assistant response, compaction done | `core-api/src/bus.rs` |
| `SystemEventBus` | 64 | provider (un)registered, config key updated, job completed, session cancelled, **user created/deleted/active-changed/mounts-changed**, **global connectors changed, connector reinstalled** | `core-api/src/system_bus.rs` |
| `SystemEventBus` | 64 | provider (un)registered, config key updated, job completed, session cancelled, **user created/deleted/active-changed/mounts-changed**, **global connectors changed, connector reinstalled**, **report created** | `core-api/src/system_bus.rs` |
| `GlobalEvent` (per-user) | 512 | all `ServerEvent` variants → WS clients + inbox lifecycle | `core-api/src/events.rs` |
Plus internal `mpsc` queues: per-source `SourceInbox` (message serialization) and a central `notify` queue (background agents → user).
@@ -129,8 +129,8 @@ Two rules keep the boundary real, and both are enforced by the compiler:
The schema is split into two buckets (§5.1), and the split is the point:
- **`create_registry_tables`** — instance-wide, readable without any user key: `users`, `roles`, `llm_providers`, `llm_models`, `transcribe_models`, `tts_models`, `image_generate_models`, `plugins`, `plugin_access` + `plugin_user_configs`, `approval_rules`, `tool_permission_groups`, `config`, `known_tools`, `llm_requests`, `mcp_catalog`, `mcp_global_servers` + `mcp_global_access`, `oauth_providers`, `role_capabilities`, `shared_folders` + `shared_folder_members`, `projects` + `project_members`. The MCP tables back the Connectors model (§7/§14/§15 — see its own section); `oauth_providers` (accessor `db/oauth_providers.rs`) holds one row per identity provider (Google…) — endpoints + `client_id`/`client_secret` + `redirect_uri`, admin-owned household secrets (§4/§15b), never a per-user token. The last two pairs are junction-backed membership: `shared_folder_members` (accessor `db/shared_folders.rs`) for the on-disk shared folders (§6), `project_members` (accessor `db/project_members.rs`) for projects (see the Projects section) — both let a member be read-only (`can_write`) and both drive the container mount topology + the fs routing. Their FKs are registry→registry (same file), which is allowed — unlike an owner→registry key.
- **`create_owner_tables`** — one owner's content, **identical schema in every file that has it**: `chat_sessions`, `chat_sessions_stack`, `chat_history`, `chat_llm_tools`, `chat_summaries`, `session_scratchpad`, `session_mcp_grants`, `stack_mcp_grants`, `scheduled_jobs`, `job_runs`, `system_agent_runs`, `system_agent_state`, `mcp_user_servers`, `mcp_events`, `sources`, `secrets`, `llm_request_payloads`, `memory_docs` (+ FTS5 `memory_docs_fts`). `mcp_user_servers` (a user's activated per-user connectors) carries `catalog_name` as a **bare `TEXT` snapshot** of `mcp_catalog.name`, never a FK — an owner→registry key would fail every INSERT; for an OAuth connector it also snapshots `oauth_provider` + `deliver_json`, and its `api_key` column holds the refresh token (in the SQLCipher-encrypted file, so no column crypto). Because `memory_docs` is an owner table, one definition backs **private** memory in each `{userid}.db` and **shared** memory in `system.db` (the household owner) — see the memory namespace note below. (`projects`/`project_tickets` were owner tables in the single-user past: projects are shareable now, so `projects` + `project_members` are registry tables and `project_tickets` is gone.)
- **`create_registry_tables`** — instance-wide, readable without any user key: `users`, `roles`, `llm_providers`, `llm_models`, `transcribe_models`, `tts_models`, `image_generate_models`, `plugins`, `plugin_access` + `plugin_user_configs`, `approval_rules`, `tool_permission_groups`, `config`, `known_tools`, `llm_requests`, `mcp_catalog`, `mcp_global_servers` + `mcp_global_access`, `oauth_providers`, `role_capabilities`, `shared_folders` + `shared_folder_members`, `projects` + `project_members`, `supervision`, `system_agent_coverage`. The MCP tables back the Connectors model (§7/§14/§15 — see its own section); `oauth_providers` (accessor `db/oauth_providers.rs`) holds one row per identity provider (Google…) — endpoints + `client_id`/`client_secret` + `redirect_uri`, admin-owned household secrets (§4/§15b), never a per-user token. The last two pairs are junction-backed membership: `shared_folder_members` (accessor `db/shared_folders.rs`) for the on-disk shared folders (§6), `project_members` (accessor `db/project_members.rs`) for projects (see the Projects section) — both let a member be read-only (`can_write`) and both drive the container mount topology + the fs routing. Their FKs are registry→registry (same file), which is allowed — unlike an owner→registry key.
- **`create_owner_tables`** — one owner's content, **identical schema in every file that has it**: `chat_sessions`, `chat_sessions_stack`, `chat_history`, `chat_llm_tools`, `chat_summaries`, `session_scratchpad`, `session_mcp_grants`, `stack_mcp_grants`, `scheduled_jobs`, `job_runs`, `system_agent_runs`, `system_agent_state`, `mcp_user_servers`, `mcp_events`, `sources`, `secrets`, `llm_request_payloads`, `memory_docs` (+ FTS5 `memory_docs_fts`), `reports`. `mcp_user_servers` (a user's activated per-user connectors) carries `catalog_name` as a **bare `TEXT` snapshot** of `mcp_catalog.name`, never a FK — an owner→registry key would fail every INSERT; for an OAuth connector it also snapshots `oauth_provider` + `deliver_json`, and its `api_key` column holds the refresh token (in the SQLCipher-encrypted file, so no column crypto). Because `memory_docs` is an owner table, one definition backs **private** memory in each `{userid}.db` and **shared** memory in `system.db` (the household owner) — see the memory namespace note below. (`projects`/`project_tickets` were owner tables in the single-user past: projects are shareable now, so `projects` + `project_members` are registry tables and `project_tickets` is gone.)
Schema is greenfield (no migrations, §0), but a purely **additive** column lands on an existing DB in place: `db::ensure_column` runs `ALTER TABLE … ADD COLUMN` and swallows the "duplicate column" error, a no-op on a fresh DB where the `CREATE TABLE` already has the column. Used for the OAuth columns on `mcp_catalog` / `mcp_user_servers` so a dev box need not be wiped for an additive change (a full recreate is still valid).
@@ -138,6 +138,10 @@ Schema is greenfield (no migrations, §0), but a purely **additive** column land
**Memory namespace (blueprint §5).** `memory_docs` (accessor `db/memory_docs.rs` — `get`/`upsert`/`list`/`search`(FTS)/`delete`) backs a virtual note store surfaced through the fs-tools, **not** the disk. Two sibling roots (not the blueprint's nested `memory/{userid}` + `memory/shared`): `user-memory/…` routes to the caller's own pool (`ToolContext::pool`), `shared-memory/…` to the system pool (a singleton captured in `fs::register_all`). `tools/fs/classify_memory()` decides on the raw first path component (a `..` in the tail clamps inside the store, never escapes to disk); `read_file`/`write_file`/`list_files`/`edit_file`/`insert_at_line`/`replace_lines`/`search_file` override `run_with` to route memory paths (each extracting a pure transform shared with its on-disk `execute`) and leave every other path on disk. The HTTP surface routes them the same way: `GET /api/file` classifies **before** `resolve_view_path` and serves the note from `memory_docs` (caller's pool / system pool), so the file viewer opens `user-memory/…` and `shared-memory/…` like any file, and `show_file_to_user` accepts memory paths too (existence-checked on the right pool). Approval (seeded in `seed_fs_path_rules`): `user-memory/*` is `@fs_any allow` (private, frictionless); `shared-memory/*` is `@fs_read allow` + `@fs_write require` — reads free, **writes need approval** so the agent can't silently push one person's data into shared memory. `grep_files` stays disk-only (regex-across-tree ≠ FTS); ranked full-text recall over notes is a separate tool, `memory_search` (`tools/fs/memory_search.rs`), over the `memory_docs` FTS index — allowed by a path-less rule (it takes `query`, not `path`).
**Supervision + coverage (registry).** `supervision(subject_user_id, supervisor_user_id)` (accessor `db/supervision.rs`) is the §0.1 **supervision edge** — a generic directed edge between two users, deliberately attribute-free, whose domain reading ("a parent watches a child") lives only in seed data and UI copy. It answers two questions with one table: *whom does a background agent look at* (`subjects()`) and *who may read what it produced* (`supervisors_of()`, which is what `reports.audience = 'supervisors'` resolves against). Both FKs are registry→registry, so the cascade is real in both directions. `system_agent_coverage(agent_id, subject_user_id, covered_through)` (accessor `db/system_agent_coverage.rs`) is the per-subject watermark that makes "everything since last time" a window: it sits between `system_agent_runs` (a history for the human, skips idle passes) and `system_agent_state` (attempt marker, advances on **every** tick and **before** the work — which is precisely why it can never delimit the window the work is about), and differs from both by advancing **only on a completed pass**, so a crash re-covers rather than skips. Deriving it from the last report's `period_end` was the obvious alternative and is wrong for one ordinary reason: a supervisor deleting an old report would rewind the scheduler and regenerate the report they just discarded — a document is the user's to delete, scheduler state is not. Registry rather than owner because the pass runs in *some* supervisor's runtime and which one depends on who is logged in that night; the acting user's file would give one subject two unsynchronised clocks.
**Reports (`db/reports.rs`, blueprint §13).** The documents system agents write about a stretch of time — a daily review of a supervised account, a weekly "what you struggled to get done" digest. **The second two-homes table**, for the same reason as `memory_docs` and with the same mechanics: one owner schema, and the file a row lands in *is* its audience. A `{userid}.db` row is that user's own report, behind SQLCipher; a `system.db` row is an instance report, written *about* someone *for* the people who supervise them and therefore cleartext to whoever owns the box — deliberately, since they are the intended reader (§2). Which file a producer writes into falls out of its own `AgentScope` with no new concept (`PerUser` → `ctx.pool`, `Instance` → the registry pool it already holds), and **the subject of an instance report cannot see it** because their tools only ever reach their own pool — the invisibility is structural, so nothing anywhere filters by reader. `subject_user_id`/`producer_user_id`/`run_id` are bare snapshot columns, never FKs (owner→registry would fail every INSERT; for an instance row the `system_agent_runs` trace sits in the *acting* user's file). `kind` is producer-declared text, not an enum (§0.1). Rows are immutable but for `mark_read`, whose `read_at IS NULL` guard makes acknowledgement **shared and first-reader-wins** — two admins, one alert, dealt with once. Consequence worth internalising: since the admin cannot open the subject's encrypted sessions, **there is no click-through to the evidence** — whatever justifies a report must be narrated in its body, under the same rule the shared memory lint already follows (say which conversation and what kind of problem, without reproducing the sensitive line). **Currently there is no producer, no API and no UI** — the table, its accessor and its tests are the whole of it.
**Memory injection into the prompt**: `AgentSystemContext::load_inject_memory` (`loop_adapters/system.rs`) routes each `meta.inject_memory` entry — `user-memory/…` → owner pool, `shared-memory/…` → the shared (`system.db`) pool, both via `memory_docs::get`; anything else (`data/…`, `$WD/…`) is a disk read. The shared pool is threaded `ChatSessionManager` → `UserLoopRuntime` → `AgentSystemContext`. `assistant` and `project-coordinator` inject `user-memory/index.md` + `shared-memory/index.md`.
**Prompt substitutions**: an `AGENT.md` may carry `<!-- KEY -->` placeholders; `agents::resolve_includes` turns each into a `__KEY__` sentinel, replaced at request time. Two are resolved by the system-context source itself (`loop_adapters/system.rs`) from the session owner (`user_id`) + registry (`shared_pool`), so every source (WS, mobile, cron, sub-agents) gets them with no caller plumbing: `__SHARED_FOLDERS__` (the user's shared-folders table) and `__USER_PROFILE__` (the owner's directory profile: `Name`, `Date of birth` with age computed at build time, `Sex`, `Preferred language`, admin `Notes` — unset values render as explicit `unknown` / `not specified`, the `Notes` line is omitted when empty). Any other key comes from the per-call `SendMessageOptions::system_substitutions` map.
@@ -248,6 +252,12 @@ A **system agent** runs on a user's behalf without being asked. There are three
**`run_and_record` orders the three steps, once, for everybody**: mark the attempt (always, even for an idle pass) → `has_work` (`false` writes nothing at all, or the run log becomes a heartbeat) → open the run row, then work. The `start`/`finish` split (unlike `job_runs`, written once at the end) leaves a visible `running` row when the process dies mid-pass, swept to `failed` by the next `start` for that agent — safe precisely because the scheduler is sequential and single-instance, at both levels (agents in order, then users in order).
**`AgentScope::PerSubject` is the scope where "whose data" and "whose runtime" come apart** — the conversation review (`system_agents/conversation_review.rs`, wiring `subject_pass`) is the first and the reason it exists. The pass reads the **subject's** database and runs inside a **supervisor's** runtime, so everything it leaves behind (ephemeral session, run row) lands in the watcher's file and nothing in the watched one's; the report crosses between them via `system.db`. Three things fall out and each is load-bearing: (a) **iteration is over subjects, not supervisors** — two parents watching one child must yield one review, so whichever of them is unlocked lends a runtime and the report is filed against the subject; (b) **`is_due` is not consulted** — it keys state by agent within one file, which would collapse every subject sharing a supervisor into one clock, so due-ness lives in `system_agent_coverage` and is answered inside `has_work` (and `run_and_record` skips `mark_attempt` for this scope for the same reason); (c) **the subject need not be logged in**, via the new `UserManager::open_unencrypted` — for a user with no key the password guards the *session*, not the data, so this makes that explicit in one place and **refuses an encrypted user**, not as policy but because there is no key to be had. The rule that falls out is neutral by construction and worth quoting: *work over somebody else's history runs unattended for a user who is not encrypted, and only while they are logged in for one who is*. The returned pool is deliberately **not** registered as unlocked (that map is what "logged in" means to everything else). Authorization is the caller's: `subject_pass` is behind the `supervision` edge, never a role check.
**`meta.json: "allow_tools": false` empties the turn's tool set** (`AgentMeta::allow_tools` → `loop_adapters/runtime.rs::turn_params` swaps in an empty `ToolRegistry`): built-ins, MCP, plugin and interface tools alike, `notify` included. Distinct from a restrictive security group — a group decides whether a call is *allowed*, this decides whether the model is shown anything to *call*. For an agent whose input is other people's text, that is also the prompt-injection answer: the round an injected instruction would act in has no tools in it. The conversation review declares it, and consequently produces its report as the turn's **final assistant message** (read back with `chat_history::last_assistant_for_session`, parsed shallowly by `parse_report`: leading `# heading` → title, opening paragraph → summary, `NOTHING_TO_REPORT` sentinel → no row) rather than through a `save_report` tool, which would have needed whitelisting past the approval gate that an unattended pass auto-denies. The cost is that severity cannot come from the model; every report it files is `notice`.
**Per-pass prompt substitutions.** `run_ephemeral_turn` takes a `system_substitutions` map. The two the system context resolves by itself (`__USER_PROFILE__`, `__SHARED_FOLDERS__`) describe the *session owner*, which for a pass about somebody else is the wrong person — so the review passes the **subject's** profile under its own `<!-- SUBJECT_PROFILE -->` key (rendered by the shared `loop_adapters::system::render_user_profile_section`). It goes in the system prompt rather than the trigger message because age, name and sex change what counts as worth reporting, and the model needs them before it reads a word of the transcript.
**A locked user is skipped, and that is the normal case, not an error.** The pool is the unlock token (§9): a user who has not logged in since the last restart has no readable events, no session store — and no place to record the skip, since the only file that could hold it is the one we cannot open. Hence `system_agent_runs` has no `skipped` status: the skip is an INFO log line and nothing else.
**`AgentScope::Instance` is the ownerless-work escape hatch, and there is exactly one user of it.** The shared memory store belongs to nobody, but a pass over it still has to run *somewhere*: an ownerless run would write its trace into `system.db`, which `GET /api/system-agents/runs` shows to nobody (scoped on the caller's own pool, by design), and its `notify()` would have no recipient. So `instance_pass` runs it as the **first active unlocked admin** (`users::list` order, so the choice is stable across passes), and the whole per-user surface keeps working unchanged. Cost: it needs an admin who has logged in since the restart.
@@ -256,6 +266,12 @@ A **system agent** runs on a user's behalf without being asked. There are three
**The configured security group is not applied verbatim.** `<agent>.security_group` is an instance-wide admin setting; handing it to a restricted member's run would give their background agent a tool set their role never granted. `system_agents::configured_run_context` puts it through `run_context::reconcile_group_for_user` — the same seam a persisted group takes — degrading to the role default when the role disallows it. With nothing configured the run still starts from `role_default_run_context`, never `None`, because `None` means the catch-all group, which is *wider*.
### The conversation review
`system_agents/conversation_review.rs` — nightly, one report per supervised subject, covering **every** conversation in the window rather than one report per session (the useful signal is often *across* conversations). The window is `[covered_through, now)` and due-ness is "the watermark stops before the most recent occurrence of `run_at_hour` local" (default 4am), which is also why downtime needs no catch-up mechanism: a machine off for three days finds a three-day-old watermark and covers it in one pass. `most_recent_occurrence` is generic over the timezone so it is testable without depending on where the box is, and resolves through the timezone (not UTC arithmetic) so a DST-skipped hour is handled.
`chat_history::conversation_window` is the transcript query, and its four filters each exist because of a specific way the result would otherwise be wrong: `is_ephemeral = 0` (or a pass reads the transcript its *previous* pass was given and reports on itself), `depth = 0` (sub-agent frames are machine-to-machine), `is_synthetic = 0` (machinery-injected turns are not things the person said), `content <> ''` (an assistant row that was only a tool call). **Tool calls are absent by construction, not by filter** — they live in `chat_llm_tools` — so the review sees what was *said*, never what was *done*, and the prompt says so plainly because a model shown a gap narrates over it. Rendering is prose grouped by conversation, never JSON: a dialogue read as a dialogue is what models are best at, and nothing machine-readable comes back this way — the structured artefact is the report at the other end.
### The memory lints
`system_agents/memory_lint.rs` — one struct, two instances differing only by fields: `MemoryLintAgent::private` (`PerUser`, over `user-memory/` in the caller's pool) and `::shared` (`Instance`, over `shared-memory/` in the system pool — the same routing `classify_memory` gives the fs-tools). Prompts are two `AGENT.md`s sharing `agents/common/memory-lint.md`; the shared one additionally hunts **table-rule violations** and is told to report *which note and what kind of problem* without repeating the sensitive line, since restating it is the harm being flagged.