AI-Studio/runtime/AGENTS.md

# AGENTS.md

These instructions cover the Rust runtime in `runtime/`. They add to the `AGENTS.md` in the repository
root, which applies here as well.

## Rust Runtime (`runtime/`)
**Entry point:** `runtime/src/main.rs`

Key modules:
- `app_window.rs` - Tauri window management, updater integration
- `app_access.rs` - Session cookie which lets the app window into the .NET server
- `dotnet.rs` - Launches and manages the .NET sidecar process
- `runtime_api.rs` - Axum-based HTTPS API for .NET ↔ Rust communication
- `certificate.rs` - Generates self-signed TLS certificates for secure IPC
- `secret.rs` - Secure secret storage using OS keyring (Keychain/Credential Manager)
- `clipboard.rs` - Cross-platform clipboard operations
- `file_data.rs` - File processing for RAG (extracts text from PDF, DOCX, XLSX, PPTX, etc.)
- `encryption.rs` - AES-256-CBC encryption for sensitive data
- `pandoc.rs` - Integration with Pandoc for document conversion
- `log.rs` - Logging infrastructure using `flexi_logger`

**Every runtime API route requires the API token.** `require_api_token` in `runtime_api.rs` checks it
for all routes at once, so handlers take no `APIToken` argument. Register a new route in
`create_router`, before that call: `route_layer` protects only the routes registered before it, and
a route added afterward would be open to every process on the machine. The test
`every_route_requires_the_api_token` reads the routes from `create_router` and fails for any route
which answers without the token.

**Only the app window gets into the .NET server.** Every start makes a new UI token in `app_access.rs`.
Rust passes it to .NET as `AI_STUDIO_UI_TOKEN` through `ipc_environment` in `dotnet.rs`, and hands it to
the window as an HttpOnly session cookie before the window opens the app (`change_location_to` in
`app_window.rs`); .NET refuses every request without it. Therefore:

- Never put the token into a URL or a log line. Only a development build hands it out elsewhere:
  `startup.env` carries it to the .NET server started from Rider, together with the other secrets of the
  IPC, and the boot link in `dev-boot-link.txt` in the repository root lets another browser get the cookie.
- Keep the cookie `Lax`. A release shows `tauri://localhost` before it opens the app, and WKWebView on
  macOS withholds a `Strict` cookie on that navigation. A development build starts from the dev server
  of the Tauri CLI on `127.0.0.1`, the same site as the app, which hides the problem; start it with
  `cargo tauri dev --no-watch --no-dev-server` to see what a release sees.
- The .NET server listens on `127.0.0.1` only, and the cookie belongs to that host. Change the host in
  `APP_HOST` and in `Program.cs` together, since no test compares them. `AppAccessRuntimeAgreementTests`
  only checks that both sides use the same cookie name and environment variable.

**Only the runtime lets links leave the window.** AI Studio shows a single window, and a browser outside
it cannot show the app, since it lacks the session cookie. Therefore:

- `should_open_in_system_browser` in `app_window.rs` alone decides which address goes to the system: a
  website, another local server, or a `mailto:` or `tel:` link, but never an address of the app. The
  handlers for navigations and for new windows both ask it.
- On Linux, `open_in_system_browser` hands such an address to the desktop portal, as the Flatpak does
  anyway; the opener plugin only steps in when there is no portal. Started from an AppImage, xdg-open
  inherits the environment of the AppImage, and the browser stays closed without any error.
- The handler for new windows always denies the window. Only a window which `setup` builds itself can
  have that handler, which is why `tauri.conf.json` sets `"create": false`.
- Keep the link script of the opener plugin switched off (`open_js_links_on_click(false)`): it opens
  every link clicked while holding Shift or Ctrl in the system browser, links of the app included. The
  shell plugin has a link script as well, which cannot be switched off and opens every link with a
  target the same way.
- `link_guard.js` takes every click which would open a link somewhere else away from both scripts and
  from the page. On a link of the app, the click does nothing; on any other link, it goes on to the
  webview, whose request for a new window or a navigation reaches the runtime. Therefore, give a link
  with a target no click handler of its own: no script of the page sees its click.
- No script of the page may open or start anything, so `capabilities/default.json` grants the opener
  and shell plugins nothing. The runtime calls both from Rust, which needs no permission, e.g., to
  start the .NET server in `dotnet.rs`.

**The right-click menu shows only in text fields and on selected text,** never on a link: its other
entries, such as going back, reloading, or opening a link in a new window, make no sense in the app.
`context_menu_guard.js` hides it everywhere else, in every frame, but only in release builds, since
development builds need the menu to open the developer tools.

**Runtime API handlers never block.** All calls of the .NET app share one HTTP/2 connection, and the
task driving it may wait on exactly the Tokio worker which a blocking handler occupies, so a single
blocking handler can hold up the whole app. Therefore:

- File and disk access, the OS keyring, waiting for a `std::sync::Mutex`, and CPU-bound work such as
  loading a tokenizer or scanning text run in `tokio::task::spawn_blocking`. Follow
  `run_qdrant_edge_request` in `qdrant_edge_database.rs`, `prepare_image` and `prepare_image_sync` in
  `image.rs`, or `sanitize_batch` in `prompt_injection/api.rs`.
- When an API offers a callback, as the file dialogs do, await the callback instead of calling the
  blocking variant; see `await_dialog` in `file_actions.rs`.
- Short, bounded work, such as a single metadata lookup or writing a log line, may stay on the worker.
- When the blocking task fails, answer with an error, never with an empty value the app could take
  for a valid answer.
- Never keep a `std::sync::MutexGuard` alive across an `.await`, not even with an explicit `drop`
  before it: the future of the handler is then no longer `Send`, and Axum refuses it. Scope the guard
  in a block instead.
- `runtime_api::test_support::assert_runtime_stays_free` tests a handler which waits for a lock. Run
  such a test with `#[tokio::test(flavor = "multi_thread", worker_threads = 1)]`.

## IPC Communication Flow
1. Rust runtime starts and generates TLS certificate
2. Rust starts internal HTTPS API on random port
3. Rust launches .NET sidecar, passing: API port, certificate fingerprint, API token, secret key, UI token
4. .NET reads environment variables and establishes secure HTTPS connection to Rust
5. .NET requests an app port from Rust, starts Blazor Server on 127.0.0.1 at that port
6. Rust hands the session cookie to the Tauri webview and points it to 127.0.0.1:app_port
7. Bi-directional communication: .NET ↔ Rust via HTTPS API