diff --git a/session-logs/2026-05-30-guruconnect-specs.md b/session-logs/2026-05-30-guruconnect-specs.md new file mode 100644 index 0000000..0dde522 --- /dev/null +++ b/session-logs/2026-05-30-guruconnect-specs.md @@ -0,0 +1,159 @@ +# Session Log — 2026-05-30 GuruConnect Feature Specifications + +## User +- **User:** Mike Swanson (mike) +- **Machine:** Mikes-MacBook-Air.local +- **Role:** admin + +## Session Summary + +The session opened with building HTML show notes for the 2026-05-30 radio show episode ("Promised vs Got and Inventions"). Created a professionally formatted HTML version from the existing markdown show prep, added color-coded sections, phone hook callouts, and responsive styling using the March 28 show notes as a template. The HTML file was committed and opened in browser for review. + +The bulk of the session focused on processing three GuruConnect feature requests and producing comprehensive technical specifications. Mike requested "Mac/Linux/Other agents" support, triggering the `/gc-feature-request` skill workflow. Created SPEC-010 for cross-platform agent support (macOS and Linux), specifying platform abstraction traits for capture/input/encoding with macOS using ScreenCaptureKit/VideoToolbox and Linux using X11 XShm/VA-API. Priority set to P2 (elevated from existing roadmap P3) due to market criticality—all major competitors support multi-platform. Estimated effort: X-Large (12-16 weeks). + +Mike then requested mobile agent support (iOS/Android as remote control targets, not mobile viewer apps). Created SPEC-011 specifying native Swift/SwiftUI iOS app with ReplayKit screen sharing (view-only, no input injection due to sandboxing) and Kotlin/Jetpack Compose Android app with MediaProjection capture plus Accessibility Service input injection. Both use same protobuf-over-WSS protocol with support-code authentication and push notifications (APNs/FCM). Documented platform constraints: foreground-only operation, user consent required per session, iOS fundamentally view-only. Priority P3, effort X-Large (16-20 weeks, requires mobile development expertise). + +Mike's third request was for "headless Linux mode - provides direct tty access." Initial interpretation was PTY shell access (like SSH). After presenting SPEC-012 draft, Mike clarified he wanted "remote console" access (as if sitting at the physical machine). Updated SPEC-012 to include dual modes: Serial Console Mode (direct /dev/ttyS0 access for GRUB bootloader, kernel boot messages, kernel panics—like KVM-over-IP Serial-over-LAN) and PTY Shell Mode (interactive bash/zsh for normal server management). Dashboard shows mode selector ("Console" vs "Shell" buttons) for headless agents. Serial console requires root privileges and one-time GRUB configuration. Priority P2, effort Medium (5-7 weeks). + +## Key Decisions + +- **SPEC-010 priority elevation:** Promoted from existing roadmap P3 to P2 because multi-platform support is market-critical (ScreenConnect, Splashtop, AnyDesk all support macOS/Linux; GuruConnect's Windows-only limitation blocks adoption). +- **SPEC-011 mobile target interpretation:** User requested mobile "agents" (devices as remote control targets), not mobile viewer apps. This is technically challenging due to sandboxing; spec documents limitations prominently (iOS view-only, foreground-only sessions, consent-first model). +- **SPEC-011 vs GuruRMM SPEC-017 distinction:** GuruConnect SPEC-011 is remote control of mobile devices; GuruRMM SPEC-017 is MDM/inventory management. Documented as complementary, not overlapping. +- **SPEC-012 dual-mode architecture:** User clarified "remote console" meant boot-level access (GRUB, kernel messages), not just shell. Added Serial Console Mode alongside PTY Shell Mode. Serial console provides true KVM-over-IP equivalent (text mode). +- **SPEC-012 security model:** Serial console mode requires root (boot-level control risk); recommend separate RBAC permission (console_access vs shell_access) and MFA for console mode (Phase 2). +- **Platform abstraction approach (SPEC-010):** Refactor existing Windows code behind traits (PlatformCapture, PlatformInput, PlatformEncoder, PlatformTray) rather than duplicating logic. macOS and Linux implementations go in platform-specific modules. +- **Mobile app architecture (SPEC-011):** iOS uses ReplayKit broadcast extension (App Group for shared data), Android uses MediaProjection foreground service. Input injection via AccessibilityService on Android only (iOS cannot inject input without jailbreak). + +## Configuration Changes + +**GuruConnect repository (`azcomputerguru/guru-connect`):** +- Created: `docs/specs/SPEC-010-cross-platform-agents.md` (359 lines) +- Created: `docs/specs/SPEC-011-mobile-agents.md` (483 lines) +- Created: `docs/specs/SPEC-012-headless-linux-tty.md` (628 lines initially, then 352 additions for dual-mode update) +- Modified: `docs/FEATURE_ROADMAP.md` — added SPEC-010 (P2, Future Considerations), SPEC-011 (P3, Future Considerations), SPEC-012 (P2, Core Remote Control section) + +**ClaudeTools repository (`azcomputerguru/claudetools`):** +- Created: `projects/radio-show/episodes/2026-05-30-promised-vs-got-and-inventions/show-notes.html` (343 lines) +- Modified: `projects/msp-tools/guru-connect` submodule pointer — advanced through 5 commits (SPEC-010, SPEC-011, SPEC-012 initial, SPEC-012 dual-mode update) + +**Commit sequence:** +1. `df25e91` - feat(radio): add HTML show notes for 2026-05-30 episode +2. `1c0b119` - feat(radio): add HTML show notes (after rebase) +3. `5e23255` - spec: add SPEC-010 Cross-Platform Agent Support (macOS and Linux) [guru-connect] +4. `4890649` - chore: update GuruRMM submodule to ad63b35 [separate — GuruRMM SPEC-017 + credential management roadmap item] +5. `75c4c47` - chore: bump guru-connect submodule (SPEC-010 cross-platform agents) +6. `b186280` - spec: add SPEC-011 Mobile Agent Support (iOS and Android) [guru-connect] +7. `fcbeae3` - chore: bump guru-connect submodule (SPEC-011 mobile agents) +8. `a062a82` - spec: add SPEC-012 Headless Linux Mode (Direct TTY Access) [guru-connect] +9. `95dfbe1` - chore: bump guru-connect submodule (SPEC-012 headless Linux TTY) +10. `761bae5` - spec: update SPEC-012 to include both Serial Console + PTY Shell modes [guru-connect] +11. `5bdb0c4` - chore: bump guru-connect submodule (SPEC-012 dual-mode update) + +## Credentials & Secrets + +No new credentials created. All specs use existing GuruConnect authentication model (support codes, per-agent keys from SPEC-004). + +**Certificates/provisioning referenced:** +- SPEC-010 macOS: requires Apple Developer Program ($99/year, already in place) for code signing + notarization +- SPEC-011 iOS: requires Apple Developer Program for APNs + App Store; Google Play Developer account ($25 one-time) for Play Store +- SPEC-011 push: Firebase project (free tier) for FCM + +## Infrastructure & Servers + +**GuruConnect coordination:** +- Specs added to standalone `azcomputerguru/guru-connect` repo +- Submodule tracked at `projects/msp-tools/guru-connect` in claudetools repo +- No deployment changes (specs are proposed, not implemented) + +**Radio show notes:** +- HTML file location: `projects/radio-show/episodes/2026-05-30-promised-vs-got-and-inventions/show-notes.html` +- Markdown source: `show-prep.md` in same directory + +## Commands & Outputs + +**Ollama classification attempt (failed):** +```bash +curl -s http://localhost:11434/api/generate -d '{"model":"qwen3.6:latest",...}' +# Result: {"error":"model 'qwen3.6:latest' not found"} +# Fallback: Used qwen3:14b (available), but returned empty JSON +# Proceeded with manual classification +``` + +**GuruConnect submodule operations:** +```bash +cd projects/msp-tools/guru-connect +git add docs/specs/SPEC-NNN-*.md docs/FEATURE_ROADMAP.md +git commit -m "spec: add SPEC-NNN ..." +# (did not push — pushing triggers CI) + +cd ../../.. +git add projects/msp-tools/guru-connect +git commit -m "chore: bump guru-connect submodule (SPEC-NNN ...)" +``` + +**Sync operations:** +- Multiple `/sync` commands throughout session to pull incoming work from GURU-5070 (27 commits related to GuruConnect v2 dashboard development) +- Final session shows repos fully synchronized + +## Pending / Incomplete Tasks + +**SPEC-010 (Cross-Platform Agents):** +- Implementation requires 12-16 weeks +- Dependencies: macOS/Linux test infrastructure, SPEC-004 deterministic machine identity completion +- Blocked by: resource allocation decision + +**SPEC-011 (Mobile Agents):** +- Implementation requires 16-20 weeks + mobile development expertise +- Dependencies: Apple Developer + Google Play accounts, Firebase project, mobile developer hire/contract +- Open question: iOS view-only limitation acceptable to market? (Answer: yes, competitors same) +- Open question: Android Accessibility Service onboarding friction — need step-by-step wizard + +**SPEC-012 (Headless Linux TTY):** +- Implementation requires 5-7 weeks +- Dependencies: extends SPEC-010 Linux agent (can implement in parallel with or after SPEC-010) +- Open questions: + 1. Serial console permissions: root vs capabilities (CAP_SYS_TTY_CONFIG)? + 2. RBAC for console vs shell access (recommend yes: separate permissions) + 3. MFA for console mode (defer to Phase 2 broader MCP feature) + 4. Default mode if serial console unavailable (recommend auto-fallback to shell with warning) + +**Radio show:** +- HTML notes ready for Saturday 2026-05-30 broadcast +- If show date slips, refresh Segment 3 items (current tech news dated May 2026) + +## Reference Information + +**Specs created:** +- SPEC-010: Cross-Platform Agent Support (macOS and Linux) — `guru-connect/docs/specs/SPEC-010-cross-platform-agents.md` +- SPEC-011: Mobile Agent Support (iOS and Android) — `guru-connect/docs/specs/SPEC-011-mobile-agents.md` +- SPEC-012: Headless Linux Mode (Serial Console + PTY Shell) — `guru-connect/docs/specs/SPEC-012-headless-linux-tty.md` + +**Roadmap updates:** +- SPEC-010: P2, Future Considerations section +- SPEC-011: P3, Future Considerations section +- SPEC-012: P2, Core Remote Control section (between web viewer and multi-monitor switching) + +**Commit SHAs (GuruConnect):** +- `5e23255` - SPEC-010 +- `b186280` - SPEC-011 +- `a062a82` - SPEC-012 initial +- `761bae5` - SPEC-012 dual-mode update + +**Commit SHAs (ClaudeTools):** +- `df25e91` / `1c0b119` - radio show HTML +- `75c4c47` - SPEC-010 submodule bump +- `fcbeae3` - SPEC-011 submodule bump +- `95dfbe1` - SPEC-012 submodule bump +- `5bdb0c4` - SPEC-012 dual-mode submodule bump + +**External references:** +- GuruRMM SPEC-017: Mobile Device Support (MDM/inventory) — distinct from GuruConnect SPEC-011 (remote control) +- SPEC-002: v2 modernization architecture (per-agent keys model used by all three new specs) +- SPEC-004: Stable machine identity (dependency for SPEC-010 and SPEC-012) +- ADR-001: GuruConnect is standalone (no RMM coupling) + +**Related files:** +- Radio show prep: `projects/radio-show/episodes/2026-05-30-promised-vs-got-and-inventions/show-prep.md` +- Radio show HTML: `projects/radio-show/episodes/2026-05-30-promised-vs-got-and-inventions/show-notes.html` +- Previous HTML template: `session-logs/2026-03-28-show-notes.html`