feat(workspace): admin system prompt shared with all users

[serrrfirat]

Summary

• Introduces SYSTEM.md in a well-known __admin__ scope so admins can set a system prompt that all tenants receive
• Gated behind multi-tenant mode at both API and prompt assembly layers — zero overhead in single-user deployments
• New admin-only API endpoints: GET/PUT /api/admin/system-prompt with 64 KB size limit

Closes #2088

How it works

1. Admin writes SYSTEM.md to __admin__ scope via PUT /api/admin/system-prompt
2. In system_prompt_for_context_inner(), when admin_prompt_enabled is true, reads SYSTEM.md directly from __admin__ scope
3. Injected as "## System Instructions" section before per-user identity files
4. Injection scanning protects against prompt injection in admin content

Multi-tenancy gating

• API layer: Handlers check workspace_pool.is_some() → 404 in single-user mode
• Prompt layer: admin_prompt_enabled flag on Workspace — set by WorkspacePool and in app.rs when has_any_users() is true

Files changed

File	Change
src/workspace/document.rs	paths::SYSTEM, ADMIN_SCOPE, is_reserved_scope()
src/workspace/mod.rs	Injection scan list, admin_prompt_enabled field/builder, gated read in prompt assembly
src/app.rs	Enable admin_prompt_enabled on owner workspace in multi-tenant mode
src/channels/web/server.rs	.with_admin_prompt() in WorkspacePool, route registration
src/channels/web/handlers/system_prompt.rs	New — GET/PUT handlers with 64 KB limit
src/channels/web/handlers/users.rs	Reserved scope validation on user creation
src/channels/web/types.rs	Request/response DTOs
tests/admin_system_prompt.rs	New — 6 integration tests

Test plan

• cargo clippy --all --all-features — zero warnings
• cargo test --lib — 4289 passed
• cargo test --test admin_system_prompt --features libsql — 6 passed
• Manual test: admin sets prompt via API, agent picks it up in conversation

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request implements an admin system prompt feature for multi-tenant environments, enabling global instructions to be defined in a reserved "admin" scope and injected into all user prompts. Key additions include management API handlers, routing, and safety checks to prevent user ID collisions with system scopes. Feedback highlights the need for a content size limit on the system prompt to avoid token exhaustion or context overflow.

[gemini-code-assist]

The put_handler lacks a content size limit for the system prompt. Since this content is injected into every user's system prompt, an unbounded size could lead to token budget exhaustion or context overflow. A 64 KB limit is recommended.

pub async fn put_handler(
    State(state): State<Arc<GatewayState>>,
    AdminUser(_admin): AdminUser,
    Json(req): Json<SystemPromptRequest>,
) -> Result<Json<SystemPromptResponse>, (StatusCode, String)> {
    if req.content.len() > 64 * 1024 {
        return Err((StatusCode::PAYLOAD_TOO_LARGE, "System prompt exceeds 64 KB limit".to_string()));
    }
    // Gate behind multi-tenant mode.
    if state.workspace_pool.is_none() {
        return Err((
            StatusCode::NOT_FOUND,
            "System prompt management requires multi-tenant mode".to_string(),
        ));
    }

    let db = state.store.as_ref().ok_or((
        StatusCode::SERVICE_UNAVAILABLE,
        "Database not available".to_string(),
    ))?;

    let ws = Workspace::new_with_db(ADMIN_SCOPE, Arc::clone(db));

    let doc = ws.write(paths::SYSTEM, &req.content).await.map_err(|e| {
        let status = if matches!(e, crate::error::WorkspaceError::InjectionRejected { .. }) {
            StatusCode::BAD_REQUEST
        } else {
            StatusCode::INTERNAL_SERVER_ERROR
        };
        (status, e.to_string())
    })?;

    Ok(Json(SystemPromptResponse {
        content: doc.content,
        updated_at: Some(doc.updated_at.to_rfc3339()),
    }))
}

[henrypark133]

Code Review Summary

Severity	Count
Warning	2
Nit	2

Rust safety: Clean — no unwraps in production paths, let-chain syntax valid for edition 2024 / MSRV 1.92, ADMIN_SCOPE write isolation correct.

Open Questions

• Is the owner-workspace asymmetry (warning 2) acceptable, or should it be documented before merge?
• Is PUT "" the intended way to clear the system prompt? No DELETE endpoint, and not documented.

Test Coverage Notes

• 6 workspace-layer integration tests are well-structured and cover the critical behavioral paths.
• The 64 KB limit is untested because it's not implemented — needs a test once added.
• HTTP handler gate (single-user → 404) is not tested.

[henrypark133]

[warning | Logic Completeness] The PR description states a "64 KB size limit" but this handler has no content-length check. An admin can write multi-MB content that is injected verbatim into every user's system prompt, silently exhausting token budgets.

gemini-code-assist already flagged this; the limit remains unimplemented.

Suggested fix — add at the start of put_handler:

if req.content.len() > 64 * 1024 {
    return Err((StatusCode::PAYLOAD_TOO_LARGE, "System prompt exceeds 64 KB limit".to_string()));
}

Also add a corresponding test case in tests/admin_system_prompt.rs.

[serrrfirat]

Done — added the 64 KB size limit at the top of put_handler (before the multi-tenant gate) and two regression tests:

• put_rejects_oversized_system_prompt — verifies 413 for content > 64 KB
• put_accepts_system_prompt_within_limit — verifies content at exactly 64 KB passes the size check

See commit 4efa4cb.

[henrypark133]

[warning | Behavioral Regression] is_multi_tenant is evaluated once at startup. If the server starts with no users (single-user mode) and users are added later, the owner workspace frozen in Arc never gets admin_prompt_enabled. Meanwhile WorkspacePool::build_workspace unconditionally calls .with_admin_prompt() for every tenant workspace.

Practical impact: an admin writes a system prompt then tests via CLI — they don't see it. All HTTP users do. This asymmetry is surprising.

Minimal fix: document that the owner workspace requires a server restart after the first user is created to activate admin_prompt_enabled. If full consistency is needed, move the check inside system_prompt_for_context_inner or make the flag reactive.

[serrrfirat]

Done — added a documentation comment block at the is_multi_tenant check explaining the startup-time evaluation behavior: the owner workspace requires a server restart after the first user is created to activate admin prompts. Tenant workspaces via WorkspacePool are unaffected since they always call .with_admin_prompt().

See commit 4efa4cb.

[ilblackdragon]

Verdict: Request changes

• src/channels/web/handlers/system_prompt.rs — PR description claims a 64 KB size limit, but the handler only inherits the global 10 MB body limit. Either add the explicit cap or correct the description.
• src/workspace/mod.rs:1578 — admin-prompt read uses if let Ok(doc) = …, silently swallowing DB outages as "no admin prompt". Log at debug!; only DocumentNotFound should be silent.
• src/workspace/document.rs — unrelated rustdoc deletions on DocumentMetadata/HygieneMetadata/PatchResult. Should be reverted to keep the diff focused.
• Cache: every turn pays an extra DB read for the admin doc — cache on WorkspacePool with invalidation on PUT.
• Tests: only #[cfg(feature = "libsql")], contrary to the dual-backend rule. No handler-level tests for non-admin auth rejection, oversize body, or injection rejection. No If-Match/audit log on PUT (admin prompt changes affect every tenant).

[serrrfirat]

@ilblackdragon Addressed the first two items in 4efa4cb:

64 KB size limit — Added an explicit MAX_SYSTEM_PROMPT_SIZE (64 KB) check at the top of put_handler, before the multi-tenant gate. Returns 413 Payload Too Large if exceeded. Two regression tests added: one for oversized content (expects 413) and one for content at exactly 64 KB (expects not-413).

Owner workspace asymmetry — Added a documentation comment block at the is_multi_tenant check in app.rs explaining the startup-time evaluation: the owner workspace requires a server restart after the first user is created to activate admin prompts. Tenant workspaces via WorkspacePool are unaffected.

Still outstanding from your review:

• Silent error swallowing on admin-prompt read (if let Ok(doc) in mod.rs:1578) — will add debug! logging so only DocumentNotFound is silent
• Unrelated rustdoc deletions on DocumentMetadata/HygieneMetadata/PatchResult — will revert
• Cache for admin doc on WorkspacePool with invalidation on PUT

[ilblackdragon]

Code Review

What it does: Adds shared SYSTEM.md under reserved __admin__ scope, injected into every tenant's prompt in multi-tenant mode, with admin-only GET/PUT /api/admin/system-prompt (64 KB cap) and a pool-wide invalidation cache. Injection scanning is wired through Workspace::write and actually rejects (not just logs).

Real problems

• src/app.rs:15-31 startup-only is_multi_tenant. The owner Workspace is frozen in Arc without with_admin_prompt() if the server boots with zero users. After the first user is added, non-web channels (Telegram, REPL, CLI) which use the owner workspace will never see the admin prompt until restart. The PR comment documents the restart caveat for the owner workspace but not the channel-coverage gap. Either always call with_admin_prompt() and make the read a no-op single-user, or signal a 0→1 user transition.
• Stale cache foot-gun (src/workspace/mod.rs read_admin_prompt). The pool cache is invalidated only by the PUT handler's success path. Any other code path that writes __admin__/SYSTEM.md (memory tools, future skills, tests) will desync silently. Test feat: Add Google Suite & Telegram WASM tools #9 documents this as expected. Wire invalidation into Workspace::write() when path == paths::SYSTEM && scope == ADMIN_SCOPE, or use a short TTL.
• src/workspace/document.rs:282-284 is_reserved_scope is exact-match, case-sensitive. __Admin__, __admin__\n, or trailing whitespace bypass. Normalize (trim().eq_ignore_ascii_case) and reserve the whole __*__ namespace.
• src/channels/web/handlers/system_prompt.rs:113-126 — size check runs before the multi-tenant gate; flip so single-user always returns 404 regardless of payload size (avoids state leak).
• Add a route-scoped DefaultBodyLimit::max(128 * 1024) to reject oversized bodies before JSON parse (the global 10 MB limit allows the parse).
• src/channels/web/handlers/users.rs:71-77 — reserved-scope validation on a freshly-minted UUID is dead code; move guard to repository layer.

Test gaps

No 401/403 tests for non-admin/unauth, no single-user 404 test, test #8 asserts != 413 and would pass on 500s — replace with real round-trip, no PUT→injection-rejection integration test, no test for the startup-only is_multi_tenant regression.

Verdict: Approve with changes. The is_multi_tenant channel gap and cache desync are the load-bearing fixes.

[ilblackdragon]

Approving — pushed the minor fixes directly: reserved-scope check is now case-insensitive and reserves the whole __*__ namespace, the admin system-prompt route gets a 128 KB DefaultBodyLimit layer to reject oversized bodies before JSON parse, and the dead UUID-collision check in user creation is removed. The two larger items from the review (startup-only is_multi_tenant gap for non-web channels, and admin-prompt cache invalidation only firing from the PUT handler) are not addressed here — leaving them as follow-ups since they need more design discussion.