AGENTS.md · risa-labs-inc/BossConsole

Sections

1. Project Overview
2. Essential Commands
3. Workflow Rules
4. Architecture
5. Remote UI property patches are tri-state
6. Plugin dependencies are resolved at install time
7. The tools menu shows a scrollbar only when it scrolls
8. Retiring a plugin into another one
9. Configuration
10. Microkernel Mode's toggle is applied on restart, not in the running process
11. Logging
12. Browser native disposal
13. JxBrowser's native libraries swap the process's malloc zones when they load
14. Browser telemetry, and how to turn it off
15. Two-finger swipe navigation (macOS)
16. Build and Deployment
17. Development Notes
18. Key Files
19. Deep Links
20. Every OS open request becomes a boss:// link

First lines (shown under the repo's Apache-2.0 license)

# AGENTS.md

This file provides guidance to coding agents working with this repository.

## Project Overview

BOSS (Business Operating System Service) is a desktop application built with Kotlin Multiplatform and Compose Multiplatform. It features WebAuthn/passkey authentication, integrated browser (JxBrowser), terminal integration (BossTerm), customizable keyboard shortcuts, and role-based access control.

**Target Platforms**: Desktop only (macOS, Windows, Linux).

## Essential Commands

```bash
./gradlew run                    # Run desktop application
./gradlew showVersion           # Display current version
./gradlew test                  # Run tests
./gradlew build                 # Build application
./gradlew packageDmg            # Build macOS DMG
./gradlew packageMsi            # Build Windows MSI
./gradlew packageDistributionForCurrentOS  # Linux packages
./gradlew incrementVersion      # Increment patch version
```

## Workflow Rules

**IMPORTANT**: Do NOT run `./gradlew run` in a blocking/foreground way just to test - the user runs and tests the app themselves. **Exception:** launching the app **in a dedicated bottom split pane is allowed** (backgrounded so it doesn't wedge the pane).

### Testing automatic app updates

On macOS, closing the last main window keeps BOSS running in the Dock. A Dock click
or File > New Window opens a window again; explicit Quit ends the application.

Automatic Updates in Settings downloads new releases and prepares installation after
manual quit. On macOS it also installs when no main windows remain, including when
the download finishes after the last window closes. That idle update relaunches
with `--no-window`, keeping BOSS in the Dock until a Dock click or New Window request.
Explicit Quit installs the staged update and leaves BOSS closed. Release distributions default this on;
Gradle development runs default it off. Explicit preferences are saved. Update
banners and prompts stay hidden in automatic mode; progress and errors remain in
Settings. The next start of a newer version shows a one-time success toast.

Build a separate older distribution for installation testing:

```bash
./gradlew :composeApp:createDistributable -PtestAutoUpdate=true
```

This uses v1.0.0, enables automatic updates by default, stores updater preferences in
`composeApp/build/auto-update-test-settings`, and writes the distribution under
`composeApp/build/compose-auto-update-test/binaries/main/app/`. On macOS, manually
launch `BOSS.app` from that directory. Quit manually to let the helper install, then
open it again after installation finishes. Closing all main windows instead tests
the idle install and windowless relaunch. The incoming release must support
`--no-window` to remain windowless after installation. Native Quit requests remain
pending through Compose cleanup and then complete, so BOSS does not cancel macOS logout,
restart, or shutdown. Do not use `run` for installation testing:
the updater refuses automatic installation from a Gradle development process.

### Automatic plugin updates

Settings > Updates has an independent Automatic Plugin Updates switch. It defaults
on in packaged release builds and off in Gradle development runs. Preferences persist.
Every eligible plugin is included by default. The per-plugin list stores explicit opt-outs,
so newly installed plugins update automatically too. Opt-outs are rechecked before activation.
The worker starts after workspace restoration, uses compatible store candidates, and
waits for all plugin tabs and mounted panels to close. It rechecks views after download;
a reopened view defers installation again. Downloads use `.part` files until admitted.
Failed promoted artifacts are quarantined; a `.rejected-update` marker fences startup
selection if a live loader prevents removal. Host and Toolbox updates/installVersion
share SHA-256 plugin-ID file locks under `.plugin-update-locks`; never delete lock files.
Both participants claim a process gate before opening a lease descriptor. Their
String-only system properties use keys `boss.plugins.updateLease.protocol3.` followed
by SHA-256 of the UTF-8 canonical lock-file path, with UUID String ownership tokens.
Capture the Properties object and computed key once per acquisition. Properties.putIfAbsent
admits exactly one owner; every existing value is busy, including foreign values. Never
replace an occupied value. Remove only the exact owning String token after confirmed
successful channel closure. No host/plugin objects or access contexts enter global state;
Properties.store/list remain string-compatible. Keep this protocol identical to Toolbox's
PluginUpdateProcessRegistry and PluginUpdateLease. Closing a second same-process descriptor
can release the holder's POSIX OS lock, so busy contenders must never open it. isOpen=false
alone is not proof after a failed native close; any uncertain close retains its token across
repeated closes and requires restarting BOSS. Registry mutation, clearing properties, or
System.setProperties by arbitrary in-process code is outside this cooperative protocol;
plugins already share JVM/file access. Both host and Toolbox releases must use protocol 3
for the shared guarantee. Persistent disk lock names remain SHA-256 of the plugin ID.
Ordinary idle plugins reload without restarting BOSS; native plugins, disabled plugins,
plugins with loaded dependents, and multiwindow updates are staged for the next manual
start. Disabled plugins remain disabled. Protected API/runtime ids use their existing
host-managed lifecycle. Activation failures attempt to restore the previous JAR; status
and errors appear in Settings. Supabase Realtime is the primary trigger, with a six-hour
fallback and a local 30-second check for views closing. Three failed attempts pause
that release for this process; a new release gets a fresh budget. Busy views and another
installer's lock do not consume attempts.

Toolbox honors the optional `boss.plugins.autoUpdate.enabled` JVM property to suppress
manual update toasts in automatic mode. The `boss.plugins.autoUpdate.optOuts` property
keeps manual prompts available for explicitly excluded plugins. Its companion change needs to ship too; older
Toolbox builds may still show a manual prompt. Turning the mode off stops pending work
before activation; already-staged updates apply at the next manual start.

### `composeApp` test home isolation

Every `composeApp` `Test` task points `user.home` at its own fresh
`composeApp/build/test-home/<task-name>` directory. Keep the redirect and the per-run deletion:
`ProjectState` persists recent projects asynchronously and retains only ten, so tests using the
real home can evict entries from a developer's project picker and a reused test home makes later
runs race a stale `recent-projects.json` load. This guarantee is deliberately module-local;
moving a test that reads `BossDirectories.rootDir` to another module requires equivalent isolation
there.

### A `@Test` that returns a value never runs

`fun x() = runBlocking { ...; assertIs<T>(y) }` returns whatever its last expression does, and JUnit
Jupiter does not execute a `@Test` method that returns a value: it reports a WARNING-level discovery
issue, which Gradle does not print, and counts the method nowhere. Nine `composeApp` tests sat
unexecuted that way, four of them the MCP approval gate's fail-closed guarantees, and one no longer
described the code by the time it first ran (#1667). Declare an expression-bodied test `(): Unit =`,
or write `runBlocking<Unit>`, as `plugin-loader`'s tests already do.

Every module's Gradle `Test` task now sets `junit.platform.discovery.issue.severity.critical=WARNING`
(root `build.gradle.kts`), `buildSrc` sets it in its own build file because it is a separate build
the root never reaches, and `composeApp` repeats it in
`src/desktopTest/resources/junit-platform.properties` so an IDE run meets it too. A discovery issue
aborts discovery for the whole engine: every test in the module disappears and a single
`initializationError` names the method. If a toolchain bump introduces an unrelated warning, relax
the property to `ERROR` in that module's own `build.gradle.kts`, which wins over the root; do not
delete it.

**The property is only read by JUnit Platform 1.13 and later.** On an older platform it is silently
ignored, the guard does nothing, and a passing test run looks exactly the same as a working guard.
That is why `buildSrc` imports the root version catalog and pins `platform(junit-bom)` to
`libs.versions.junit.jupiter` (#1709): its only other test dependency, `kotlin("test")`, resolves
JUnit through Gradle's embedded Kotlin (Platform 1.10), and the guard there was inert until the pin.
The BOM is not a redundant dependency; removing it restores the inert guard. To check a module, run
a throwaway `@Test fun probe() = 42` and confirm the run fails with "must not return a value".

### Running commands in a visible terminal pane

When a terminal MCP server is available, prefer it over the plain `Bash` tool for commands worth showing - it runs in a visible BossTerm pane and still returns stdout/stderr/exit code. Two servers may be present depending on which app hosts the session; use whichever the session's `SessionStart` hook designates:

- **`mcp__boss__*`** - exposed by the `terminal-tab` plugin inside BossConsole (e.g. `mcp__boss__run_command`, `run_in_sidebar`).
- **`mcp__bossterm__*`** - exposed by the standalone BossTerm app.

For a bottom split use `panel: horizontal_split`. Reuse a pane across calls by passing back its `pane_id`. Keep plain `Bash` for trivial read-only commands where opening a visible pane is churn. (Do not mix the two servers in one session - they target different app instances.)

## Architecture

### Module Structure
- **`composeApp/`** - Main Compose Multiplatform UI application
- **`server/`** - Minimal Ktor server component
- **`modules/`** - Microkernel / out-of-process architecture Gradle modules
  (`boss-ipc`, `boss-service-*`, `boss-orchestrator`, `boss-ui-sdk`,
  `boss-mastery-*`, `boss-app-*`). They keep flat Gradle paths (`:boss-ipc`),
  only the directory lives under `modules/`; excluded on Windows-ARM64 (no
  protoc binary). `boss-ipc`/`boss-ui-sdk` publish as upstream jars consumed by
  the standalone `boss-microkernel-runtime` repo.
- **`plugin-platform/`** - Host-side plugin platform / SDK modules
  (`plugin-loader`, `plugin-repository`, `plugin-api-core`, …). This is the
  infrastructure that loads and runs plugins, **not** the plugins themselves -
  those live in the separate `boss_plugins` repo.