# πŸ“‹ FACTORY WORK ORDER: CrossTalk βž” Sidecar Native Integration **To:** Mike 14.0 (Lead Architect, CrossTalk OS & WorkBench) **From:** Zack 3.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, Unified Workspace Schema & Return Protocol --- ## 1. Executive Briefing: The Death of Zoo Code & The 15-Second Freeze Mike, The Factory is officially preparing to drop the wrecking ball on Visual Studio Code, the `Zoo Code` extension, and the fragile `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 touches his mouse or clicks another chat window during those 15 seconds, the macro misfires and fails. 2. **The Electron Memory Tax:** VS Code idles between 1.5 GB and 2.5 GB of RAM. On a 16 GB Apple Silicon machine running multiple simultaneous agent workflows, that memory footprint is unacceptable. 3. **No Native Distributed IPC:** VS Code cannot be controlled over macOS 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 under 200 milliseconds. * **Autonomy:** Runs an actor-isolated `AgentRunner` engine with streaming OpenRouter and local Ollama connections. * **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 concluding until a verified clean build is recorded. * **Two-Way IPC:** Operates natively on `FactoryKit`'s distributed notification bus (`NotificationCenter.postDistributed`). Your job in this Work Order is to **connect CrossTalk directly to Sidecar**, upgrade the Staging HUD, eliminate legacy scaffolding, and establish sub-millisecond task dispatch and in-memory return reporting. --- ## 2. The Unified Blueprint Schema (Eliminating `set_project`) ### The Problem with `set_project`: Historically, dispatching a Code Monkey required an awkward two-step PDS payload: 1. Action 1: `// Meta: {"action": "set_project", "project_name": "..."}` 2. Action 2: `// Meta: {"action": "code_monkey"}` This was clunky scaffolding. It wasted prompt tokens, risked desynchronization if an agent forgot step 1, and completely failed in monorepo workspaces where Frank needs to touch a shared framework and immediately validate it inside a companion test app in a single run. ### The New Standard: Atomic, Self-Describing Blueprints We are officially retiring `set_project`. Every `code_monkey` PDS block is now completely self-contained. The blueprint body itself explicitly defines the workspace and targets: ```markdown # Workspace: Factory_Frameworks ## Task 1: Add Token Refresh Endpoint - **Target:** DriveKit - **Context:** Files involved, anchor points. - **Instructions:** - Logic rules and architectural constraints. ## Task 2: Verify in Test Harness - **Target:** Framework Test Harness - **Context:** Test harness caller file. - **Instructions:** - Invoke new API and verify clean execution. ``` *(For standalone apps, `# Workspace: ZooKeeper` and `- **Target:** ZooKeeper` are simply identical).* ### Multi-Target Monorepo Autonomy: Because Sidecar commands Apple's native `XcodeSwitchScheme` tool, Sidecar's engine reads this schema and handles multi-target workflows in a single execution loop: 1. Edits `DriveKit` source files. 2. Calls `XcodeSwitchScheme(schemeName: "DriveKit")` βž” `BuildProject`. 3. Edits `Framework Test Harness` test files. 4. Calls `XcodeSwitchScheme(schemeName: "Framework Test Harness")` βž” `BuildProject`. 5. Verifies both schemes pass cleanly before granting completion! --- ## 3. CrossTalk Staging HUD Upgrades (Header Sniffer & Instant Dismissal) ### A. The Blueprint Header Sniffer When CrossTalk intercepts a `code_monkey` PDS block, its parser will sniff the top of the Markdown body: 1. **Workspace Extraction:** Reads `# Workspace: [Name]` (or `# Project: [Name]`). 2. **Registry Resolution:** Calls `FactoryRegistryManager.shared` to resolve the root path: * If a standalone `.xcodeproj` βž” resolves the project directory. * If a monorepo workspace (`workspaceUUID` present) βž” resolves the `.xcworkspace` master container path. 3. **Target / Scheme Detection:** Scans sub-headers for `- **Target:** [SchemeName]` to identify all build schemes involved. 4. **Auto-Populate HUD:** Pre-selects the resolved workspace and scheme badges in the HUD automatically. ### B. Runner Toggle: `[ Sidecar (Native) | Zoo Code (Legacy) ]` Add a clean segmented control in the HUD header or settings: * **`Sidecar (Native)` [Default]:** * Clicking "Dispatch" skips the Keyboard Maestro macro completely. * Writes the staged envelope to disk in ~1 ms. * Fires the distributed IPC notification. * **Dismisses the HUD instantly (under 10 milliseconds). The BossMan never waits.** * **`Zoo Code (Legacy)`:** * Retains the existing fallback Keyboard Maestro trigger during initial transition trials until we permanently decommission VS Code. ### C. Calling Agent Attribution (`callingAgent`) The HUD must capture the name of the active chat agent who authored the PDS block (e.g., `"Pete 2.0"`, `"Frank 2.0"`, `"Annie 2.0"`). This ensures Sidecar returns completion receipts directly to the correct window. --- ## 4. The Outbound Wire: Staged Task Envelope Protocol ### Why Prompts Do Not Travel in Notification Dictionaries: `NSDistributedNotificationCenter` messages travel across Mach/XPC ports. Placing a 500-line Markdown blueprint with code blocks and quotes into `userInfo` causes XPC payload truncation or quote-escaping corruption. ### The Staged Envelope Flow: CrossTalk writes the raw, unescaped UTF-8 string to a temporary file, then sends a lightweight notification pointing to that path: ```text β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ 1. CrossTalk Staging (Dispatcher) β”‚ β”‚ β€’ Writes task to: /tmp/sidecar_task_[UUID].json β”‚ β”‚ β€’ Pure UTF-8, zero escaping, instant disk write. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό (<500-byte distributed IPC pulse) β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ 2. Distributed Notification (The Bell) β”‚ β”‚ Name: "com.higginsoft.sidecar.dispatch" β”‚ β”‚ userInfo: { β”‚ β”‚ "pds_request_id": "[UUID]", β”‚ β”‚ "task_file_path": "/tmp/sidecar_task_[UUID].json" β”‚ β”‚ } β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ 3. Sidecar Intake β”‚ β”‚ β€’ Catches notification in memory. β”‚ β”‚ β€’ Bounces window to front: NSApp.activate. β”‚ β”‚ β€’ Reads envelope and starts autonomous execution! β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` ### The Envelope Schema (`/tmp/sidecar_task_[UUID].json`): ```json { "taskID": "E8AD8463-C80B-4A50-B8AA-37C003766ABD", "projectName": "Factory_Frameworks", "projectPath": "/Users/dave/warezfactory/xcode/Factory_Workspaces/Factory_Frameworks", "model": "nvidia/nemotron-3-ultra-550b-a55b:free", "taskPrompt": "# Workspace: Factory_Frameworks\n\n## Task 1: Update DriveKit...", "systemPrompt": null, "callingAgent": "Frank 2.0" } ``` --- ## 5. The Inbound Return Wire: Instant Delivery via `PDSRouter.reply` ### Dead Drops Are Permanently Retired: Sidecar does **not** write `.sidecar_result.json`. CrossTalk does not need file-system watchers, polling timers, or existence checks. ### The Distributed Reply: When Sidecar's execution loop finishes (and the compile-before-complete gate confirms zero errors), Sidecar calls `PDSRouter.reply(to: notification, with: resultData)`. The reply is broadcast on the system bus under: `com.higginsoft.sidecar.dispatch.reply` ### Return Payload Schema (`userInfo`): ```text - "status": "completed" (or "stopped", "error") - "task_id": "[UUID]" - "project_name": "Factory_Frameworks" - "summary": "[Full Markdown completion report with files touched, line ranges & verified build checkmarks]" - "duration_seconds": 28.4 - "tool_count": 5 - "pds_request_id": "[UUID]" ``` ### What CrossTalk Does With The Return: 1. Catches `com.higginsoft.sidecar.dispatch.reply` on `@MainActor`. 2. Matches `pds_request_id` or `task_id` against 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. Frank 2.0). If that agent's window is closed, routes it to their `Postmaster` inbox. --- ## 6. WorkBench 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" ] ``` ### Sidecar Response: * Sidecar catches the notification. * Calls `NSApp.activate(ignoringOtherApps: true)` to bring its window to the front. * Selects the project target in its header picker and scopes all tools and Xcode workspace sessions to that directory. * **Elapsed time: ~3 milliseconds.** --- ## 7. Implementation Blueprint for Mike | Step | Action | Channel / Artifact | Responsibility | | :--- | :--- | :--- | :--- | | **1** | **Header Sniffer** | CrossTalk PDS Parser | Parse `# Workspace:` and `- **Target:**` from `code_monkey` block; deprecate `set_project`. | | **2** | **HUD Dispatch** | Staged Envelope | Write `/tmp/sidecar_task_[UUID].json` and fire `com.higginsoft.sidecar.dispatch`. Dismiss HUD instantly. | | **3** | **Return Listener** | Distributed Reply | Listen for `com.higginsoft.sidecar.dispatch.reply`; format and route `[SYSTEM_ALERT]` to `callingAgent`. | | **4** | **WorkBench Switcher**| Distributed Command | Broadcast `com.higginsoft.sidecar.open_project` on right-click project jumps. | | **5** | **Runner Toggle** | HUD Header / Settings | Provide `[ Sidecar (Native) \| Zoo Code (Legacy) ]` toggle during transition. | The tracks on the Sidecar side are compiled, verified, and listening on the bus. Once you wire these five items into CrossTalk, the entire Factory development loop will run 100% native on Apple Silicon! ```