@lattices/cli 0.3.0 → 0.4.0

package/README.md

@@ -4,16 +4,62 @@
 
 # lattices
 
-A workspace control plane for macOS. Manage persistent terminal sessions,
-tile and organize your windows, and index the text on your screen — all
-controllable from the CLI or a 30-method daemon API.
+The agentic window manager for macOS.
+
+Tile windows with hotkeys, manage persistent tmux sessions, index screen
+text with OCR, and give AI agents a 35-method desktop API — all from a
+native menu bar app and CLI.
+
+**[lattices.dev](https://lattices.dev)** · [Docs](https://lattices.dev/docs/overview) · [Download](https://github.com/arach/lattices/releases/latest)
 
 ## Install
 
+### Download the app
+
+Grab the signed DMG from the [latest release](https://github.com/arach/lattices/releases/latest):
+
+```sh
+# Or direct download:
+curl -LO https://github.com/arach/lattices/releases/latest/download/Lattices.dmg
+open Lattices.dmg
+```
+
+Drag **Lattices.app** into Applications. On first launch, a setup wizard
+walks you through granting Accessibility, Screen Recording, and choosing
+your project directory.
+
+### Install the CLI
+
 ```sh
 npm install -g @lattices/cli
 ```
 
+The CLI and app work independently — use either or both.
+
+### Build from source
+
+```sh
+git clone https://github.com/arach/lattices.git
+cd lattices
+
+# Build the menu bar app (requires Swift 5.9+ / Xcode 15+)
+cd app && swift build -c release && cd ..
+
+# Install CLI dependencies
+npm install
+
+# Launch
+node bin/lattices-app.js build   # bundle the .app
+node bin/lattices-app.js         # launch it
+```
+
+To build a signed, notarized DMG for distribution:
+
+```sh
+# Requires a Developer ID certificate and notarytool keychain profile
+./scripts/build-dmg.sh
+```
+
 ## Quick start
 
 ```sh
@@ -77,8 +123,8 @@ Bundle related repos as tabs in one session. Each tab gets its own
 pane layout from its `.lattices.json`.
 
 ```sh
-lattices group talkie      # Launch iOS, macOS, Web, API as tabs
-lattices tab talkie iOS    # Switch to the iOS tab
+lattices group vox         # Launch iOS, macOS, Web, API as tabs
+lattices tab vox iOS       # Switch to the iOS tab
 ```
 
 ## Window tiling and awareness
@@ -97,16 +143,31 @@ lattices scan recent           # Browse scan history
 lattices scan deep             # Trigger a Vision OCR scan now
 ```
 
+## Voice commands (beta)
+
+Speak to control your workspace — tile windows, search, focus apps,
+and launch projects with natural language. Powered by
+[Vox](https://github.com/arach/vox) for transcription and
+local NLEmbedding for intent matching, with Claude fallback for
+ambiguous commands.
+
+Trigger with `Hyper+3` (configurable). Press Space to speak, Space to
+stop. The panel shows what was heard, the matched intent, extracted
+parameters, and execution results.
+
 ## A programmable desktop
 
-The menu bar app runs a daemon with 30 RPC methods and 5 real-time
+The menu bar app runs a daemon with 35 RPC methods and 5 real-time
 events over WebSocket. Anything you can do from the app, an agent or
 script can do over the API.
 
 ```js
 import { daemonCall } from '@lattices/cli/daemon-client'
 
-const windows = await daemonCall('windows.list')
+// Search windows by content — title, app, session tags, OCR
+const results = await daemonCall('windows.search', { query: 'myproject' })
+
+// Launch and tile
 await daemonCall('session.launch', { path: '/Users/you/dev/frontend' })
 await daemonCall('window.tile', { session: 'frontend-a1b2c3', position: 'left' })
 
@@ -115,6 +176,14 @@ await daemonCall('ocr.scan')
 const errors = await daemonCall('ocr.search', { query: 'error OR failed' })
 ```
 
+Or from the CLI:
+
+```sh
+lattices search myproject           # Find windows by content
+lattices search myproject --deep    # Include terminal tab/process data
+lattices place myproject left       # Search + focus + tile in one step
+```
+
 Claude Code skills, MCP servers, or your own scripts can drive your
 desktop the same way you do.
 
@@ -125,12 +194,15 @@ lattices                    Create or reattach to session
 lattices init               Generate .lattices.json
 lattices ls                 List active sessions
 lattices kill [name]        Kill a session
+lattices search <query>     Search windows by title, app, session, OCR
+lattices search <q> --deep  Deep search: index + terminal inspection
+lattices place <query> [pos]  Deep search + focus + tile
+lattices focus <session>    Raise a session's window
 lattices tile <position>    Tile frontmost window
 lattices group [id]         Launch or attach a tab group
 lattices tab <group> [tab]  Switch tab within a group
 lattices scan               View current screen text
 lattices scan search <q>    Search indexed text
-lattices scan recent [n]    Browse scan history
 lattices scan deep          Trigger Vision OCR now
 lattices app                Launch the menu bar app
 lattices help               Show help
@@ -148,7 +220,11 @@ lattices help               Show help
 
 ## Docs
 
-[lattices.dev/docs](https://lattices.dev/docs/overview)
+Full documentation at [lattices.dev/docs](https://lattices.dev/docs/overview), including:
+
+- [API reference](https://lattices.dev/docs/api) — all 35 daemon methods
+- [Layers](https://lattices.dev/docs/layers) — workspace layers and tab groups
+- [Voice commands](https://lattices.dev/docs/voice) — Vox integration
 
 ## License
 

package/app/Package.swift

@@ -7,7 +7,14 @@ let package = Package(
     targets: [
         .executableTarget(
             name: "Lattices",
-            path: "Sources"
+            path: "Sources",
+            resources: [
+                .copy("../Resources/tap.wav"),
+            ]
+        ),
+        .testTarget(
+            name: "LatticesTests",
+            path: "Tests"
         )
     ]
 )

package/app/Sources/AdvisorLearningStore.swift

@@ -0,0 +1,90 @@
+import Foundation
+
+/// Captures moments where the Claude advisor resolved something the local matcher couldn't.
+/// Each entry records the transcript, what the local system matched (or missed), and what
+/// the advisor suggested that the user accepted.
+///
+/// For now this is append-only — just growing the dataset. Future work can use it to
+/// improve local matching without needing the advisor.
+
+final class AdvisorLearningStore {
+    static let shared = AdvisorLearningStore()
+
+    struct Entry: Codable {
+        let timestamp: String
+        let transcript: String
+        let localIntent: String?
+        let localSlots: [String: String]
+        let localResultCount: Int
+        let advisorIntent: String
+        let advisorSlots: [String: String]
+        let advisorLabel: String
+    }
+
+    private let fileURL: URL
+    private let queue = DispatchQueue(label: "com.lattices.advisor-learning")
+    private static let isoFmt: ISO8601DateFormatter = {
+        let f = ISO8601DateFormatter()
+        f.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        return f
+    }()
+
+    private init() {
+        let dir = FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent(".lattices")
+        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        fileURL = dir.appendingPathComponent("advisor-learning.jsonl")
+    }
+
+    /// Record that the user engaged with an advisor suggestion.
+    func record(
+        transcript: String,
+        localIntent: String?,
+        localSlots: [String: String],
+        localResultCount: Int,
+        advisorIntent: String,
+        advisorSlots: [String: String],
+        advisorLabel: String
+    ) {
+        let entry = Entry(
+            timestamp: Self.isoFmt.string(from: Date()),
+            transcript: transcript,
+            localIntent: localIntent,
+            localSlots: localSlots,
+            localResultCount: localResultCount,
+            advisorIntent: advisorIntent,
+            advisorSlots: advisorSlots,
+            advisorLabel: advisorLabel
+        )
+
+        queue.async {
+            guard let data = try? JSONEncoder().encode(entry),
+                  var line = String(data: data, encoding: .utf8) else { return }
+            line += "\n"
+
+            if let handle = try? FileHandle(forWritingTo: self.fileURL) {
+                handle.seekToEndOfFile()
+                handle.write(line.data(using: .utf8)!)
+                handle.closeFile()
+            } else {
+                try? line.data(using: .utf8)?.write(to: self.fileURL)
+            }
+
+            DiagnosticLog.shared.info("AdvisorLearning: captured [\(transcript)] → \(advisorIntent)(\(advisorSlots))")
+        }
+    }
+
+    /// Read all entries (for analysis).
+    func allEntries() -> [Entry] {
+        guard let data = try? String(contentsOf: fileURL, encoding: .utf8) else { return [] }
+        return data.components(separatedBy: "\n").compactMap { line in
+            guard !line.isEmpty, let d = line.data(using: .utf8) else { return nil }
+            return try? JSONDecoder().decode(Entry.self, from: d)
+        }
+    }
+
+    var entryCount: Int {
+        guard let data = try? String(contentsOf: fileURL, encoding: .utf8) else { return 0 }
+        return data.components(separatedBy: "\n").filter { !$0.isEmpty }.count
+    }
+}

package/app/Sources/AgentSession.swift

@@ -0,0 +1,377 @@
+import Foundation
+
+// MARK: - Persistent Claude CLI Agent
+
+/// Manages a persistent Claude conversation via `--session-id` + `--resume`.
+/// Each query spawns a `claude -p` process that resumes the same session.
+/// Uses `--output-format stream-json` for structured response parsing.
+/// The conversation context carries over between calls via session persistence.
+
+final class AgentSession: ObservableObject {
+    let model: String
+    let label: String
+    private(set) var sessionId: UUID
+
+    @Published var isReady = false
+    @Published var lastResponse: AgentResponse?
+    @Published var sessionStats: SessionStats = .empty
+
+    struct SessionStats {
+        let inputTokens: Int
+        let outputTokens: Int
+        let cacheReadTokens: Int
+        let cacheCreationTokens: Int
+        let contextWindow: Int
+        let costUSD: Double
+        let numTurns: Int
+
+        static let empty = SessionStats(inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, contextWindow: 0, costUSD: 0, numTurns: 0)
+
+        /// How full is the context? 0.0–1.0
+        var contextUsage: Double {
+            guard contextWindow > 0 else { return 0 }
+            let totalInput = inputTokens + cacheReadTokens + cacheCreationTokens
+            return Double(totalInput) / Double(contextWindow)
+        }
+    }
+
+    private var claudePath: String?
+    private let queue = DispatchQueue(label: "agent-session", qos: .userInitiated)
+    private var callCount = 0
+    private var busy = false
+
+    /// Optional override for the system prompt. If set, used instead of the default advisor prompt.
+    var customSystemPrompt: (() -> String)?
+
+    init(model: String, label: String) {
+        self.model = model
+        self.label = label
+        self.sessionId = UUID()
+    }
+
+    // MARK: - Lifecycle
+
+    func start() {
+        guard let resolved = Preferences.resolveClaudePath() else {
+            DiagnosticLog.shared.warn("AgentSession[\(label)]: claude CLI not found")
+            return
+        }
+        claudePath = resolved
+        DiagnosticLog.shared.info("AgentSession[\(label)]: ready (model=\(model), claude=\(resolved), session=\(sessionId.uuidString.prefix(8)))")
+        DispatchQueue.main.async { self.isReady = true }
+    }
+
+    func stop() {
+        DispatchQueue.main.async {
+            self.isReady = false
+            self.callCount = 0
+        }
+    }
+
+    // MARK: - Communication
+
+    /// Send a message and get a response via callback (main thread).
+    func send(message: String, callback: @escaping (AgentResponse?) -> Void) {
+        guard isReady else {
+            callback(nil)
+            return
+        }
+        guard !busy else {
+            DiagnosticLog.shared.info("AgentSession[\(label)]: busy, skipping")
+            callback(nil)
+            return
+        }
+
+        queue.async { [weak self] in
+            guard let self = self else { return }
+            self.busy = true
+            let response = self.call(prompt: message)
+            self.busy = false
+
+            DispatchQueue.main.async {
+                self.lastResponse = response
+                callback(response)
+            }
+        }
+    }
+
+    // MARK: - Claude CLI call
+
+    private func call(prompt: String) -> AgentResponse? {
+        let timer = DiagnosticLog.shared.startTimed("AgentSession[\(label)] call")
+
+        guard let claudePath = claudePath else { return nil }
+
+        let proc = Process()
+        proc.executableURL = URL(fileURLWithPath: claudePath)
+
+        var args = [
+            "-p", prompt,
+            "--model", model,
+            "--output-format", "stream-json",
+            "--max-budget-usd", String(format: "%.2f", Preferences.shared.advisorBudgetUSD),
+            "--permission-mode", "plan",
+            "--no-chrome",
+        ]
+
+        if callCount == 0 {
+            // First call: create session with system prompt
+            args.append(contentsOf: [
+                "--session-id", sessionId.uuidString,
+                "--system-prompt", customSystemPrompt?() ?? buildSystemPrompt(),
+            ])
+        } else {
+            // Subsequent calls: resume existing session (context carries over)
+            args.append(contentsOf: ["--resume", sessionId.uuidString])
+        }
+
+        proc.arguments = args
+
+        var env = ProcessInfo.processInfo.environment
+        env.removeValue(forKey: "CLAUDECODE")
+        proc.environment = env
+
+        let outPipe = Pipe()
+        let errPipe = Pipe()
+        proc.standardOutput = outPipe
+        proc.standardError = errPipe
+
+        do {
+            try proc.run()
+        } catch {
+            DiagnosticLog.shared.warn("AgentSession[\(label)]: launch failed — \(error)")
+            DiagnosticLog.shared.finish(timer)
+            return nil
+        }
+
+        proc.waitUntilExit()
+        DiagnosticLog.shared.finish(timer)
+
+        let output = String(data: outPipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let stderr = String(data: errPipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+
+        if !stderr.isEmpty {
+            DiagnosticLog.shared.info("AgentSession[\(label)] stderr: \(stderr.prefix(200))")
+        }
+
+        guard !output.isEmpty else {
+            DiagnosticLog.shared.info("AgentSession[\(label)]: empty response")
+            return nil
+        }
+
+        // Parse stream-json output — extract text and stats
+        let parsed = parseStreamJSON(output)
+
+        // Update session stats
+        let stats = parsed.stats
+        DispatchQueue.main.async {
+            self.sessionStats = stats
+        }
+
+        if stats.contextWindow > 0 {
+            let pct = Int(stats.contextUsage * 100)
+            DiagnosticLog.shared.info("AgentSession[\(label)]: context \(pct)% (\(stats.inputTokens + stats.cacheReadTokens + stats.cacheCreationTokens)/\(stats.contextWindow)) cost=$\(String(format: "%.4f", stats.costUSD))")
+        }
+
+        guard let text = parsed.text, !text.isEmpty else {
+            DiagnosticLog.shared.info("AgentSession[\(label)]: no text in response")
+            return nil
+        }
+
+        // Auto-reset session if context usage > 75%
+        if stats.contextUsage > 0.75 {
+            DiagnosticLog.shared.warn("AgentSession[\(label)]: context at \(Int(stats.contextUsage * 100))%, resetting session")
+            sessionId = UUID()  // Fresh session ID
+            callCount = 0       // Next call will create a fresh session
+        } else {
+            callCount += 1
+        }
+
+        DiagnosticLog.shared.info("AgentSession[\(label)]: \(text.prefix(120))")
+        return AgentResponse.parse(text: text)
+    }
+
+    struct ParsedResponse {
+        let text: String?
+        let stats: SessionStats
+    }
+
+    /// Parse stream-json output lines, extract text and session stats from the result line.
+    private func parseStreamJSON(_ output: String) -> ParsedResponse {
+        let lines = output.components(separatedBy: "\n")
+        var resultText: String?
+        var stats = SessionStats.empty
+
+        for line in lines {
+            guard let data = line.data(using: .utf8),
+                  let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { continue }
+
+            let type = json["type"] as? String
+
+            if type == "result" {
+                resultText = json["result"] as? String
+                let numTurns = json["num_turns"] as? Int ?? 0
+                let costUSD = json["total_cost_usd"] as? Double ?? 0
+
+                // Usage stats
+                let usage = json["usage"] as? [String: Any] ?? [:]
+                let inputTokens = usage["input_tokens"] as? Int ?? 0
+                let outputTokens = usage["output_tokens"] as? Int ?? 0
+                let cacheRead = usage["cache_read_input_tokens"] as? Int ?? 0
+                let cacheCreation = usage["cache_creation_input_tokens"] as? Int ?? 0
+
+                // Context window from modelUsage
+                var contextWindow = 0
+                if let modelUsage = json["modelUsage"] as? [String: Any] {
+                    for (_, v) in modelUsage {
+                        if let m = v as? [String: Any], let cw = m["contextWindow"] as? Int {
+                            contextWindow = cw
+                        }
+                    }
+                }
+
+                stats = SessionStats(
+                    inputTokens: inputTokens,
+                    outputTokens: outputTokens,
+                    cacheReadTokens: cacheRead,
+                    cacheCreationTokens: cacheCreation,
+                    contextWindow: contextWindow,
+                    costUSD: costUSD,
+                    numTurns: numTurns
+                )
+            }
+
+            // Fallback: accumulate text from assistant content blocks
+            if resultText == nil, type == "assistant",
+               let message = json["message"] as? [String: Any],
+               let content = message["content"] as? [[String: Any]] {
+                var text = ""
+                for block in content {
+                    if block["type"] as? String == "text",
+                       let t = block["text"] as? String {
+                        text += t
+                    }
+                }
+                if !text.isEmpty { resultText = text }
+            }
+        }
+
+        return ParsedResponse(text: resultText, stats: stats)
+    }
+
+    // MARK: - System prompt
+
+    private func buildSystemPrompt() -> String {
+        let windowSummary = DesktopModel.shared.windows.values
+            .prefix(20)
+            .map { "\($0.app): \($0.title)" }
+            .joined(separator: "\n")
+
+        let intentList = PhraseMatcher.shared.catalog()
+        var intentSummary = ""
+        if case .array(let intents) = intentList {
+            intentSummary = intents.compactMap { intent -> String? in
+                guard let name = intent["intent"]?.stringValue else { return nil }
+                var slotNames: [String] = []
+                if case .array(let slots) = intent["slots"] {
+                    slotNames = slots.compactMap { $0["name"]?.stringValue }
+                }
+                let s = slotNames.isEmpty ? "" : "(\(slotNames.joined(separator: ", ")))"
+                return "\(name)\(s)"
+            }.joined(separator: ", ")
+        }
+
+        return """
+        You are an advisor for Lattices, a macOS workspace manager. You run alongside voice commands, providing commentary and follow-up suggestions.
+
+        Available commands: \(intentSummary)
+
+        Current windows:
+        \(windowSummary)
+
+        For each user message, you receive a voice transcript and what command was matched.
+
+        Respond with ONLY a JSON object:
+        {"commentary": "short observation or null", "suggestion": {"label": "button text", "intent": "intent_name", "slots": {"key": "value"}} or null}
+
+        Rules:
+        - commentary: 1 sentence max. null if the matched command fully covers the request.
+        - suggestion: a follow-up action. null if none needed.
+        - Never suggest what was already executed.
+        - Suggestions MUST include all required slots. e.g. search requires {"query": "..."}.
+        - Be terse and useful, not chatty.
+        """
+    }
+}
+
+// MARK: - Response types
+
+struct AgentResponse {
+    let commentary: String?
+    let suggestion: AgentSuggestion?
+    let raw: String
+
+    struct AgentSuggestion {
+        let label: String
+        let intent: String
+        let slots: [String: String]
+    }
+
+    static func parse(text: String) -> AgentResponse {
+        guard let jsonStr = extractJSON(from: text),
+              let data = jsonStr.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return AgentResponse(commentary: text, suggestion: nil, raw: text)
+        }
+
+        let commentary = json["commentary"] as? String
+
+        var suggestion: AgentSuggestion?
+        if let s = json["suggestion"] as? [String: Any],
+           let label = s["label"] as? String,
+           let intent = s["intent"] as? String {
+            let slots = (s["slots"] as? [String: String]) ?? [:]
+            suggestion = AgentSuggestion(label: label, intent: intent, slots: slots)
+        }
+
+        return AgentResponse(commentary: commentary, suggestion: suggestion, raw: text)
+    }
+
+    private static func extractJSON(from text: String) -> String? {
+        let cleaned = text
+            .replacingOccurrences(of: "```json", with: "")
+            .replacingOccurrences(of: "```", with: "")
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let start = cleaned.firstIndex(of: "{"),
+              let end = cleaned.lastIndex(of: "}") else { return nil }
+        return String(cleaned[start...end])
+    }
+}
+
+// MARK: - Agent Pool
+
+/// Manages the Haiku (fast advisor) and Sonnet (deep thinker) agent sessions.
+final class AgentPool {
+    static let shared = AgentPool()
+
+    let haiku = AgentSession(model: "haiku", label: "haiku")
+    let sonnet = AgentSession(model: "sonnet", label: "sonnet")
+
+    private init() {}
+
+    func start() {
+        DiagnosticLog.shared.info("AgentPool: starting haiku + sonnet sessions")
+        haiku.start()
+        // Stagger sonnet start
+        DispatchQueue.global().asyncAfter(deadline: .now() + 5) {
+            self.sonnet.start()
+        }
+    }
+
+    func stop() {
+        haiku.stop()
+        sonnet.stop()
+    }
+}