sync: auto-sync from Mikes-MacBook-Air.local at 2026-05-30 19:18:44
Author: Mike Swanson Machine: Mikes-MacBook-Air.local Timestamp: 2026-05-30 19:18:44
This commit is contained in:
159
session-logs/2026-05-30-guruconnect-specs.md
Normal file
159
session-logs/2026-05-30-guruconnect-specs.md
Normal file
@@ -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`
|
||||
Reference in New Issue
Block a user