# πŸ“‹ FACTORY WORK ORDER: CrossTalk βž” Sidecar Native Integration **To:** Mike 14.0 (Lead Architect, CrossTalk OS & WorkBench) **From:** Zack 2.0 (Fleet Commander & API Architect, ZooKeeper & Sidecar) **CC:** The BossMan **Target Target:** `CrossTalk.app` (HUD, WorkBench, & IPC Bus) **Subject:** Decommissioning Zoo Code & Keyboard Maestro: Native `Sidecar.app` Dispatch & Return Protocol --- ## 1. Executive Briefing: The Death of Zoo Code Mike, The Factory is officially preparing to drop the wrecking ball on Visual Studio Code, the `Zoo Code` extension, and the 15-second `Keyboard Maestro` macro pipeline. ### Why Zoo Code is Getting Evicted: 1. **The 15-Second Freeze:** Currently, every time the BossMan clicks "Dispatch" in your Staging HUD, a fragile Keyboard Maestro macro takes over his Mac for 15 secondsβ€”stealing window focus, executing synthetic mouse clicks, and typing keystrokes into VS Code's search boxes. If the BossMan clicks a chat window or touches his mouse during those 15 seconds, the macro fails. 2. **The Electron Memory Tax:** VS Code idles between 1.5 GB and 2.5 GB of RAM. On a 16 GB Mac running multiple agent workflows, that memory footprint is unsustainable. 3. **No Native AppleScript / Distributed IPC:** VS Code cannot be controlled via distributed system notifications or native AppleScript. ### The Successor: `Sidecar.app` We have designed, built, and verified **`Sidecar.app`**: a native, lightweight macOS application built in pure Swift 6 and SwiftUI. * **Footprint:** Idles at **~60 MB of RAM** and cold boots in 200 milliseconds. * **Autonomy:** Contains its own headless `AgentRunner` engine, native toolchain, and direct streaming connections to OpenRouter and local Ollama. * **Xcode Integration:** Communicates directly with Apple's native Xcode daemon (`xcrun mcpbridge`), commanding all 54 Apple developer tools (`BuildProject`, `GetBuildLog`, `XcodeSwitchScheme`, `XcodeOpenWorkspace`) over stdio. * **Compile Gating:** Physically blocks tasks from completing until a verified clean build is recorded. * **Two-Way IPC:** Runs natively on `FactoryKit`'s distributed notification bus (`NotificationCenter.postDistributed`). Your job in this Work Order is to **connect CrossTalk directly to Sidecar**, enabling sub-millisecond task dispatch, instant window focus, and in-memory completion reporting. --- ## 2. The Core Outbound Wire: The "Staged Envelope" Protocol ### The Problem with Sending Prompts in Notifications: `NSDistributedNotificationCenter` messages travel across macOS over XPC/Mach ports. If you attempt to send a 500-line Markdown blueprint with embedded code blocks and JSON inside a notification's `userInfo` dictionary, two bad things happen: * macOS silently drops the notification when it exceeds XPC memory limits. * Escaping quotes, backslashes, and newlines turns the prompt into a corrupted mess. ### The Solution: Staged Task Envelope on Disk CrossTalk will write the unescaped, natural task payload to a temporary file on disk, and then fire a **sub-millisecond, lightweight notification** containing the file path: ```text β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ 1. CrossTalk Staging (Dispatcher) β”‚ β”‚ β€’ Writes task to: /tmp/sidecar_task_[UUID].json β”‚ β”‚ β€’ Writes pure UTF-8 with ZERO string escaping! β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό (Sub-millisecond IPC signal: <500 bytes) β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ 2. Distributed Notification (The Bell) β”‚ β”‚ Notification Name: "com.higginsoft.sidecar.dispatch" β”‚ β”‚ userInfo: { β”‚ β”‚ "pds_request_id": "[UUID]", β”‚ β”‚ "task_file_path": "/tmp/sidecar_task_[UUID].json" β”‚ β”‚ } β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ 3. Sidecar Ingestion β”‚ β”‚ β€’ Sidecar catches notification instantly. β”‚ β”‚ β€’ Bounces to front (NSApp.activate). β”‚ β”‚ β€’ Ingests envelope and launches autonomous execution! β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` ### The JSON File Schema (`task_[UUID].json`): CrossTalk writes this file directly to `/tmp/sidecar_task_[UUID].json`: ```json { "taskID": "E8AD8463-C80B-4A50-B8AA-37C003766ABD", "projectName": "The Groovy Panda", "projectPath": "/Users/dave/warezfactory/xcode/Factory_Apps/The Groovy Panda", "model": "nvidia/nemotron-3-ultra-550b-a55b:free", "taskPrompt": "# Task\nImplement feature X...\n\n# Context\n...", "systemPrompt": null, "callingAgent": "Pete 2.0" } ``` --- ## 3. The Inbound Return Wire: Instant Delivery via `PDSRouter.reply` ### Dead Drops are Permanently Retired: `.sidecar_result.json` is completely dead for `Sidecar`. You do **not** need a directory watcher, a polling timer, or a file-existence loop. ### How Sidecar Answers CrossTalk: When `Sidecar` completes a task (and its compile gate verifies zero errors), it immediately invokes `PDSRouter.reply(to: notification, with: resultData)`. The reply arrives over the distributed bus under the notification name: `com.higginsoft.sidecar.dispatch.reply` ### The Result Payload Schema (`userInfo`): ```text - "status": "completed" (or "stopped", "error") - "task_id": "[UUID]" - "project_name": "The Groovy Panda" - "summary": "[Full Markdown completion report with file lines & checkmarks]" - "duration_seconds": 34.2 - "tool_count": 4 - "pds_request_id": "[UUID]" ``` ### What CrossTalk Does with the Reply: 1. CrossTalk catches `com.higginsoft.sidecar.dispatch.reply` on the main actor. 2. Matches `pds_request_id` or `task_id` against its active dispatch tickets. 3. Formats the completion into the standard Factory alert: ```text [SYSTEM_ALERT] Time: [Time] [summary] [/SYSTEM_ALERT] ``` 4. **Targeted Agent Delivery:** Injects the alert directly into the calling agent's prompt field (e.g. Pete 2.0). If that agent's window is closed, routes it to their `Postmaster` inbox. --- ## 4. CrossTalk Right-Click Project Switcher Currently, right-clicking an agent or project in CrossTalk's WorkBench executes: `open "vscode://file/Users/dave/warezfactory/xcode/Factory_Apps/[AppName]"` ### The Upgrade: Replace that URL scheme call with a native distributed broadcast: * **Notification Name:** `com.higginsoft.sidecar.open_project` * **Payload (`userInfo`):** ```text [ "projectName": "ZooKeeper", "projectPath": "/Users/dave/warezfactory/xcode/Factory_Apps/ZooKeeper" ] ``` ### The Effect in Sidecar: * `Sidecar` catches the notification. * Calls `NSApp.activate(ignoringOtherApps: true)` to bring its cockpit to the front. * Updates its active project picker and scopes all local tools and Xcode workspace sessions to that project directory. * **Elapsed time: ~3 milliseconds.** --- ## 5. Next-Gen HUD Upgrades (What to Add to CrossTalk's Staging Modal) Because CrossTalk is now talking directly to our own native app, you are no longer constrained by Zoo Code's limits. We can make the Staging HUD significantly smarter: ### 1. The Target Selector (Sidecar vs. Legacy Zoo Code) During the transition, add a clean toggle in the HUD header or settings: * **Runner Target:** `[ Sidecar (Native) | Zoo Code (Legacy) ]` * When `Sidecar` is selected: * The "Dispatch" button skips the Keyboard Maestro macro completely! * Writes `/tmp/sidecar_task_[UUID].json`. * Posts `com.higginsoft.sidecar.dispatch`. * The HUD dismisses **instantly** (under 10 milliseconds). The BossMan never has to wait. ### 2. Monorepo Scheme Selector For projects living inside a monorepo workspace (like Frank's `Factory_Frameworks.xcworkspace`): * If `project.workspaceUUID` is present in the registry, look up the workspace. * Show a secondary picker in the HUD for the target build scheme (e.g. `AIKit`, `BrowserKit`, `Framework Test Harness`). * Pass this in the envelope as `"targetScheme": "BrowserKit"`. ### 3. Calling Agent Field (`callingAgent`) Always stamp the name of the active chat agent who originated the PDS bundle (e.g., `"Pete 2.0"`, `"Terry 1.0"`, `"Zack 2.0"`). This ensures `Sidecar` returns the receipt to the right window every time. --- ## 6. Implementation Summary for Mike | Action | Direction | Notification / File | Details | | :--- | :--- | :--- | :--- | | **Task Dispatch** | CrossTalk βž” Sidecar | `com.higginsoft.sidecar.dispatch` | Points to `/tmp/sidecar_task_[UUID].json`. | | **Task Return** | Sidecar βž” CrossTalk | `com.higginsoft.sidecar.dispatch.reply` | Carries status, summary, and duration via `PDSRouter`. | | **Project Switch** | CrossTalk βž” Sidecar | `com.higginsoft.sidecar.open_project` | Carries `projectName` and `projectPath`. | | **HUD Dismissal** | CrossTalk Internal | UI Action | Dismisses instantly on dispatch (0 macro delay). | The tracks on the `Sidecar` side are already laid down, compiled, and listening. Once Mike hooks these wires into CrossTalk, The Factory will be 100% free of third-party IDE bloat!