Desktop Core protocol contract
Terminal retirement — local implementation, 2026-10-20
Section titled “Terminal retirement — local implementation, 2026-10-20”The current working tree removes interactive terminals and Redis while preserving command/script Remote Actions and authorized session/transcript history with existing retention. Admin has a read-only history viewer; Core advertises no terminal capability and legacy terminal operations cannot create work. This implementation is local and awaits user testing; older published implementation descriptions below remain historical. See the retirement plan and evidence.1
Boundary
Section titled “Boundary”GUI and CLI communicate with native capabilities only through the MonStaff Core local protocol. The Rust definition in crates/monstaff-core-protocol is the contract; crates/monstaff-core-client is the only client library. The Tauri GUI bridges that protocol to the renderer through six presentation commands; the renderer never receives process, collector, key or filesystem primitives.2
The former Electron context-bridge contract in packages/shared/src/types/ipc.ts was removed with the Electron client on 2026-09-05.3
Command families
Section titled “Command families”| Family | Responsibility |
|---|---|
| session | Local and TOTP login, GitHub PKCE, restore, refresh, logout and password recovery |
| projects and work items | Paginated projects, assigned and project-scoped open work items |
| timer and time entries | Start/stop, tracking-lease acquisition and takeover, manual entries, paginated history |
| monitoring | Aggregate input counters, application context, idle decisions, screenshot capture and gallery |
| permissions | Native capability state and requests for screenshot, aggregate input and active application |
| compliance | Enrollment, signed posture check, status and unenrollment |
| local AI | Policy resolution, disclosed pack install/list/remove and bounded local inference |
| agent telemetry | Client detection, hook reconciliation, per-client status and context locks |
| remote actions | Capability state and update readiness; execution stays gated by server policy |
Security invariants
Section titled “Security invariants”- Only the Core holds session tokens, the installation private key, queue keys and pack paths; clients receive bounded views.
- The local protocol is authenticated and versioned; a client with an incompatible protocol version is rejected.
- The
monstaff://callback accepts only the expected route and one-timecode/state; raw bearer-token parameters are rejected. - Queued requests are origin, method and path restricted, execute single-flight and use UUID idempotency keys with timeout, backoff and dead-letter limits.
- Device Compliance collectors and Remote Actions PTY/process primitives are never generic client commands.
Contract state
Section titled “Contract state”The Tauri renderer command surface is checked by scripts/validate-desktop-tauri-command-contract.mjs; the ordinary-user journeys are source-bound by scripts/validate-desktop-golden-contract.mjs. TypeScript bindings in the GUI are still hand-written; generating them from the Rust protocol is SDC4 of the single desktop client consolidation plan.
Change protocol
Section titled “Change protocol”- Change the Rust protocol crate and bump the protocol version when the shape changes.
- Update the Core dispatch and the client library.
- Update GUI and CLI consumers together.
- Add a protocol test covering names, argument types and result shape.
- Run the command-contract and golden-contract validators.
Projectless tracking contract — version 4
Section titled “Projectless tracking contract — version 4”StartTimer accepts either projectId or a null project with organizationId; an automatic start requires the Core agent bridge to be capturing for that organization. TimeEntry carries nullable projectId, organizationId and source. AssignTimeEntryProject reassigns a finalized allocation through the authorized backend. CLI automatic start is monstaff timer start --organization <id>. GUI, CLI and Core must ship together because the protocol version is now 4.4
Tray visual policy read
Section titled “Tray visual policy read”GetAgentTraySettings { organizationId } returns AgentTraySettings with trayWaitEnabled, trayWaitCurrentMaxMinutes and trayWaitDayMaxMinutes. The Core uses its authenticated organization-policy transport and validates maxima from 1 to 1440 minutes. This additive read carries visual settings only; live wait calculations remain in the shared TypeScript reducer. An unavailable or older backend produces neutral tray presentation. Repository-local implementation, deployment pending.5
0.3.24 delivery verification
Section titled “0.3.24 delivery verification”The dual-wait tray and projectless automatic tracking changes are now published in desktop 0.3.24, with successful exact-commit Quality, GKE backend/Admin deployment, release and promotion. Public updater/download manifests and downloaded DMG/CLI hashes were verified. Signed Apple Silicon installed-package qualification passed; extended live-feature and hidden-window checks remain separate. This supersedes the repository-local deployment-pending statements in the implementation snapshots.6
Agent live response budget
Section titled “Agent live response budget”Implemented locally for 0.3.27: GetAgentLiveStatus responses have a dedicated 8 MiB client budget; requests and ordinary responses retain 128 KiB. GUI and CLI share both declared-length and streamed-byte checks. Live history is transferred intact. On read failure the desktop shows a localized retry notice instead of empty/zero activity, and recovers automatically. The new CLI successfully read the installed Core’s history that 0.3.26 rejected. Wire format and protocol version remain unchanged; publication is pending.7
0.3.27 delivery verification
Section titled “0.3.27 delivery verification”Desktop 0.3.27 is published from 3e53752: Quality, signed release, promotion and GKE deployment succeeded. Public manifests and downloaded DMG/CLI hashes and sizes were verified; signed Apple Silicon installed-package qualification passed. This delivers the agent live-response repair and supersedes its local-only release status. The new GUI has not been verified on the user’s installation.8
Recent worked projects read
Section titled “Recent worked projects read”Locally implemented after 0.3.27: parameterless ListRecentProjects (listRecentProjects on the wire) returns the existing CoreResult::Projects envelope. Core calls authenticated GET /projects/recent; the renderer projects it independently from ListProjects. This additive read preserves existing command/result shapes and follows the existing additive tray-policy read precedent. The Tauri-only tray projection adds optional recentProjects, defaulting to empty for earlier callers. Backend and desktop/Core publication remain pending.9