codex-flow 2.1.13__py3-none-any.whl

codex_flow/data/apps/macos-overlay/README.en.md

@@ -0,0 +1,121 @@
+# macOS Native Floating Widget (FlowPilot Overlay)
+
+<div align="center">
+
+[ 简体中文 ](README.md) | [ English ](README.en.md)
+
+</div>
+
+`codex-flow-overlay` is a 100% native macOS floating widget built with **SwiftUI + AppKit**, deeply integrating the entire suite of `codex-flow usage` capabilities (live inspection, rate-limit quota monitoring, multi-session history, and aggregate efficiency analytics).
+
+---
+
+<div align="center">
+  <img src="../../docs/assets/promo/flowpilot_promo_poster.png" alt="FlowPilot Native Overlay Showcase" width="100%" style="border-radius: 12px; margin: 12px 0;" />
+</div>
+
+---
+
+## ✨ Core Highlights
+
+- 🟢 **Micro Capsule (Idle State)**:
+  - 68px diameter Frosted Glass bubble (macOS `ultraThinMaterial`);
+  - Dynamic rainbow gradient border with real-time breathing status aura;
+  - Status indicator (🟢 Idle/Complete · 🔵 Task Running · 🟠 Alert/Error);
+  - Live token badge displaying latest turn tokens (e.g. `198.2k`);
+  - Automatic half-tuck edge docking and magnetic screen snapping.
+
+- ⚡️ **Glass TabBar Control Center (Expanded State)**:
+  - **⚡️ Inspector**:
+    - **Header**: Project tag, Git branch badge, status pill, Pin lock, and collapse button;
+    - **Objective & Outcome**: Auto-extracted task goal and delivery conclusion;
+    - **3 KPI Rings**: Real-time circular gauges for Duration, Tokens, and Cost;
+    - **Rate Limits & Quota**: 5m / 1h / 1d / 7d quota progression bars and reset countdowns;
+    - **Token Distribution Bar**: Stacked breakdown of Prompt, Cached, Output, and Reasoning tokens;
+    - **Multi-Agent Topology**: Parent model reasoning effort and Worker subagent concurrency;
+    - **Skills & MCP Badges**: Automatic discovery and badge labeling of activated skills and MCP tools;
+    - **Historical Drilldown**: Inspect any past task with one-click `[⚡️ Jump to Live]`;
+    - **Action Bar**: Copy formatted summary, open Terminal console, Pin lock toggle.
+  - **📜 History**:
+    - Project filter, `All` / `Today` scope, and instant keyword search;
+    - **Chat Accordion**: Aggregates multi-turn runs into chronological chat sessions;
+    - **Session Turns**: Turn-level timeline with duration, tokens, worker badges, and quota deltas (`+1%` / `-1%`);
+    - Click any turn to inspect full details in the Inspector.
+  - **📊 Analytics**:
+    - Aggregate efficiency analysis with `7 Days` / `30 Days` toggles;
+    - Total tasks (dispatched vs. direct), active hours, and total attributed tokens;
+    - **Cache Efficiency**: Hit percentage and cached tokens saved;
+    - **Worker Offload**: Percentage of workload delegated to economic models;
+    - **Model Breakdown**: Calls, token proportions, and Parent/Worker roles;
+    - **Projects Distribution**: Multi-repository activity rankings.
+
+---
+
+## 🔒 Privacy & Demo Mode
+
+FlowPilot includes built-in privacy protection (`isPrivacyMode`):
+- All sensitive project names, prompt titles, task goals, and delivery conclusions are automatically frosted with smooth Gaussian blur filters (`blur(radius: 4.5)`).
+- Ideal for public presentations, videos, and documentation screenshots.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Build
+```bash
+bash apps/macos-overlay/build.sh
+```
+Binary output: `apps/macos-overlay/bin/FlowPilot`.
+
+### 2. Launch Daemon
+```bash
+# Start background overlay widget
+codex-flow overlay start
+
+# Or run directly
+./apps/macos-overlay/bin/FlowPilot start &
+```
+
+### 3. CLI Commands
+```bash
+# Check status
+codex-flow overlay status
+
+# Toggle expand / collapse
+codex-flow overlay toggle
+codex-flow overlay expand
+codex-flow overlay collapse
+
+# Switch tabs
+codex-flow overlay tab inspector
+codex-flow overlay tab history
+codex-flow overlay tab analytics
+
+# Inspect historical task
+codex-flow overlay show 1
+
+# Open analytics or history directly
+codex-flow overlay stats 30
+codex-flow overlay history
+
+# Update telemetry data
+codex-flow overlay update
+
+# Stop overlay
+codex-flow overlay stop
+```
+
+---
+
+## 🖱 Mouse & Keyboard Interactions
+
+| Action | Result |
+| :--- | :--- |
+| **Hover on Capsule (0.4s)** | Spring animation expands into full Glass Card |
+| **Mouse Leave (0.8s)** | Smoothly collapses back to Capsule (when unpinned) |
+| **Click Capsule / Header** | Toggle expanded/collapsed state immediately |
+| **Click Pin Icon (`📌`)** | Lock widget permanently open on top of all windows |
+| **Drag Anywhere** | Smooth desktop repositioning with screen-edge magnetic snap |
+| **Right-Click Context Menu**| Quick access to View Switcher, Pin, Refresh, Terminal, and Quit |
+| **Click "Copy Summary"** | Copies formatted run card to system clipboard |
+| **Click "Console"** | Opens `codex-flow` interactive management menu in Terminal |

codex_flow/data/apps/macos-overlay/README.md

@@ -0,0 +1,123 @@
+# macOS 原生悬浮窗 (Native Floating Widget)
+
+<div align="center">
+
+[ 简体中文 ](README.md) | [ English ](README.en.md)
+
+</div>
+
+`codex-flow-overlay` 是专为 macOS 设计的 100% 纯原生（基于 **SwiftUI + AppKit** 构建）桌面悬浮窗组件，深度集成了 `codex-flow usage` 的全部核心能力（实时巡检、配额监控、历史回溯、聚合效能分析）。
+
+---
+
+<div align="center">
+  <img src="../../docs/assets/promo/flowpilot_promo_poster.png" alt="FlowPilot Native Overlay Showcase" width="100%" style="border-radius: 12px; margin: 12px 0;" />
+</div>
+
+---
+
+## ✨ 核心特性
+
+- 🟢 **默认形态（灵动微胶囊 Micro Capsule）**：
+  - 直径 68px 的 Frosted Glass 毛玻璃拟物圆环（macOS `ultraThinMaterial`）；
+  - 外圈动态彩虹渐变边框与实时呼吸灯；
+  - 实时状态角标（🟢 空闲/完成 · 🔵 任务运行中 · 🟠 异常/告警）；
+  - 底部微缩显示最近任务的 Token 消耗徽章（如 `198.2k`）；
+  - 边缘自动半收起（Half-Tuck）与屏幕防溢出磁吸贴靠。
+
+- ⚡️ **展开态（全功能 Glass TabBar 监控台）**：
+  - **⚡️ Inspector（任务巡检）**：
+    - **Header**：项目名标签、Git 分支胶囊、任务状态徽章、Pin 锁定按钮与折叠按钮；
+    - **任务目标与交付结论卡**：智能提炼展示会话目标与交付成果；
+    - **KPI Rings**：3 组高精环形仪表盘（Time 耗时、Tokens 消耗、Cost 费用估算）；
+    - **Rate Limits & Quota**：5m / 1h / 1d / 7d 账户配额消耗百分比进度与重置倒计时；
+    - **Token 细分条**：多色堆叠胶囊条，直观呈现 Prompt、Output、Cached 与 Reasoning 思考 Token 分布；
+    - **多 Agent 路由拓扑**：展示 Parent Agent（模型与 Reasoning 强度）及各个 Worker Subagents 的独立用量与状态；
+    - **技能与 MCP 标签**：自动标注调用的 Skills 与 MCP Server 工具；
+    - **历史查看态导航**：支持回溯任意历史任务，提供一键 `[⚡️ 查看最新]` 返回实时任务；
+    - **操作底栏**：一键复制 Summary 剪贴板（带 Copied 动画反馈）、唤起终端控制台、Pin 锁定常驻。
+  - **📜 History（历史回溯）**：
+    - 多维历史会话：支持按工程过滤、`All` / `Today` 切换与实时关键词检索；
+    - **会话手风琴 (Chat Accordion)**：按会话聚合多轮任务，展示会话总 Token 与最大并发；
+    - **轮次流水线 (Session Turns)**：精确展开每一轮次的时间、耗时、Worker 标签与配额消耗差值（`+1%` / `-1%`）；
+    - 点击任意历史任务条目即刻在 Inspector 中展开深度详情。
+  - **📊 Analytics（效能看板）**：
+    - 集成聚合效能分析，支持 `7 Days` / `30 Days` 周期切换；
+    - 汇总总任务数（委派 vs 直接）、总活跃时长、总 Token 消耗与费用预估；
+    - **Cache Efficiency**：缓存命中率与节省 Token 统计；
+    - **Worker Offload**：Worker 算力委派比例仪表；
+    - **Model Breakdown**：各模型调用次数、Token 占比与角色标签（Parent/Worker）；
+    - **Projects Distribution**：多仓库/多项目活跃度排行。
+
+---
+
+## 🔒 隐私脱敏与演示模式
+
+内置 `isPrivacyMode` 隐私保护：
+- 所有敏感项目名、对话指令、任务目标与交付结论均自动采用平滑的高斯模糊滤镜（`blur(radius: 4.5)`）打码；
+- 非常适合录屏演示、公开分享与制作文档插图。
+
+---
+
+## 🚀 快速使用
+
+### 1. 编译构建
+```bash
+bash apps/macos-overlay/build.sh
+```
+编译产物位于 `apps/macos-overlay/bin/FlowPilot`。
+
+### 2. 启动悬浮窗守护进程
+```bash
+# 启动后台常驻悬浮窗
+codex-flow overlay start
+# 或直接执行二进制
+./apps/macos-overlay/bin/FlowPilot start &
+```
+
+### 3. CLI 控制指令
+```bash
+# 检查浮窗运行状态
+codex-flow overlay status
+
+# 切换展开 / 折叠
+codex-flow overlay toggle
+codex-flow overlay expand
+codex-flow overlay collapse
+
+# 切换视图选项卡
+codex-flow overlay tab inspector
+codex-flow overlay tab history
+codex-flow overlay tab analytics
+
+# 查看指定历史任务（支持 #1、#2 或 session_id）
+codex-flow overlay show 1
+
+# 打开统计看板（可指定天数）
+codex-flow overlay stats 30
+
+# 打开任务历史列表
+codex-flow overlay history
+
+# 推送并刷新最新 telemetry 运行数据
+codex-flow overlay update
+
+# 停止悬浮窗
+codex-flow overlay stop
+```
+
+---
+
+## 🖱 交互与快捷操作
+
+| 动作 | 效果 |
+|---|---|
+| **光标移入气泡停留 0.4 秒** | 触发 Spring 弹性展开为 Telemetry 卡片 |
+| **光标移出卡片区域** | 延迟 0.8 秒自动收起为圆形气泡（未 Pin 时） |
+| **单击气泡 / 顶部折叠按钮** | 立即切换展开 / 收起状态 |
+| **切换 Tab 选项卡** | 平滑切换 Inspector（任务详情）、History（任务列表）、Analytics（效能统计） |
+| **点击 History 任务条目** | 立即在 Inspector 中回溯该任务的完整 Token、费用与配额明细 |
+| **按住气泡拖拽** | 自由拖拽到屏幕任意角落（带边界贴靠保护） |
+| **右键点击** | 弹出上下文菜单（Pin 锁定、折叠/展开、打开控制台、刷新、退出） |
+| **点击「Copy Summary」** | 格式化复制任务摘要至系统剪贴板 |
+| **点击「Console」** | 快速唤起终端打开 `codex-flow` 管理控制台 |

codex_flow/data/apps/macos-overlay/Sources/Controllers/OverlayRuntimeState.swift

@@ -0,0 +1,126 @@
+import Cocoa
+
+enum OverlayGeometryActivity: Equatable {
+    case presentation
+    case snap
+}
+
+/// Small, deterministic state machine for the overlay's interaction/geometry
+/// lifecycle. It deliberately knows nothing about NSWindow animation APIs.
+///
+/// Invariants:
+/// - only one geometry activity may own the window at a time;
+/// - pointer interaction is independent of animation completion;
+/// - presentation updates requested during drag/animation are coalesced and
+///   replayed once the current owner releases the window.
+struct OverlayRuntimeState {
+    private(set) var activeGeometry: OverlayGeometryActivity?
+    private(set) var pointerInteractionActive = false
+    private(set) var pendingPresentationUpdate = false
+
+    var isGeometryTransitioning: Bool { activeGeometry != nil }
+
+    mutating func beginPointerInteraction() -> Bool {
+        guard activeGeometry == nil, !pointerInteractionActive else { return false }
+        pointerInteractionActive = true
+        return true
+    }
+
+    mutating func endPointerInteraction() {
+        pointerInteractionActive = false
+    }
+
+    /// Returns true when the caller owns the geometry immediately and should
+    /// start the presentation transition now. Otherwise the request is coalesced.
+    mutating func requestPresentationGeometry() -> Bool {
+        guard activeGeometry == nil, !pointerInteractionActive else {
+            pendingPresentationUpdate = true
+            return false
+        }
+        activeGeometry = .presentation
+        return true
+    }
+
+    /// Snap is only valid after the pointer has been released. A snap is never
+    /// queued behind another geometry owner because a drag cannot begin while
+    /// geometry is transitioning.
+    mutating func beginSnapGeometry() -> Bool {
+        guard activeGeometry == nil, !pointerInteractionActive else { return false }
+        activeGeometry = .snap
+        return true
+    }
+
+    /// Releases the current geometry owner. Returns true when a coalesced
+    /// presentation update has now acquired ownership and should be run next.
+    mutating func completeGeometry() -> Bool {
+        activeGeometry = nil
+        return claimPendingPresentationIfIdle()
+    }
+
+    /// Used after a pointer interaction ends without a snap.
+    mutating func claimPendingPresentationIfIdle() -> Bool {
+        guard pendingPresentationUpdate,
+              activeGeometry == nil,
+              !pointerInteractionActive else { return false }
+        pendingPresentationUpdate = false
+        activeGeometry = .presentation
+        return true
+    }
+}
+
+/// Filters the rectangular 76x76 NSHostingView down to what the user can
+/// actually see. This prevents the transparent host from behaving as a hover
+/// target after the compact view changes shape.
+enum OverlayCompactHitRegion {
+    static func contains(
+        _ point: NSPoint,
+        in hostBounds: NSRect,
+        expanded: Bool,
+        docked: Bool
+    ) -> Bool {
+        guard hostBounds.contains(point) else { return false }
+        if expanded { return true }
+
+        if docked {
+            let pillSize = NSSize(width: 44, height: 56)
+            let pillRect = NSRect(
+                x: hostBounds.maxX - pillSize.width,
+                y: hostBounds.midY - pillSize.height / 2,
+                width: pillSize.width,
+                height: pillSize.height
+            )
+            return pillRect.contains(point)
+        }
+
+        let center = NSPoint(x: hostBounds.midX, y: hostBounds.midY)
+        let dx = point.x - center.x
+        let dy = point.y - center.y
+        let radius: CGFloat = 31 // 58pt circle + a small allowance for its glow.
+        return dx * dx + dy * dy <= radius * radius
+    }
+}
+
+/// Synthetic AppKit tracking events may be emitted when a window resizes under
+/// a stationary pointer. Require real pointer travel before hover behavior is
+/// re-armed after a programmatic compacting/snap operation.
+struct OverlayHoverGate {
+    private(set) var suppressedAt: NSPoint?
+    let rearmDistance: CGFloat
+
+    init(rearmDistance: CGFloat = 6) {
+        self.rearmDistance = rearmDistance
+    }
+
+    mutating func suppress(at point: NSPoint) {
+        suppressedAt = point
+    }
+
+    mutating func allowsHover(at point: NSPoint) -> Bool {
+        guard let anchor = suppressedAt else { return true }
+        let dx = point.x - anchor.x
+        let dy = point.y - anchor.y
+        guard dx * dx + dy * dy >= rearmDistance * rearmDistance else { return false }
+        suppressedAt = nil
+        return true
+    }
+}

codex_flow/data/apps/macos-overlay/Sources/Controllers/OverlayScreenGeometry.swift

@@ -0,0 +1,82 @@
+import Cocoa
+
+/// Pure screen-geometry selection used by the overlay window controller.
+///
+/// `NSWindow.screen` can be temporarily nil or point at a different display while
+/// AppKit is animating/resizing a borderless panel. Geometry routing therefore
+/// derives the destination display from global coordinates instead.
+enum OverlayScreenGeometry {
+    static func bestVisibleFrame(for windowFrame: NSRect, among visibleFrames: [NSRect]) -> NSRect? {
+        guard !visibleFrames.isEmpty else { return nil }
+
+        let center = NSPoint(x: windowFrame.midX, y: windowFrame.midY)
+        if let containingCenter = visibleFrames.first(where: { $0.contains(center) }) {
+            return containingCenter
+        }
+
+        var bestIntersectionFrame: NSRect?
+        var bestIntersectionArea: CGFloat = 0
+        for candidate in visibleFrames {
+            let intersection = windowFrame.intersection(candidate)
+            guard !intersection.isNull, !intersection.isEmpty else { continue }
+            let area = intersection.width * intersection.height
+            if area > bestIntersectionArea {
+                bestIntersectionArea = area
+                bestIntersectionFrame = candidate
+            }
+        }
+        if let bestIntersectionFrame {
+            return bestIntersectionFrame
+        }
+
+        return visibleFrames.min {
+            distanceSquared(from: center, to: $0) < distanceSquared(from: center, to: $1)
+        }
+    }
+
+    /// Presentation expand/collapse is anchored at the window's top-trailing
+    /// corner. A wide panel may straddle two displays while its top-trailing
+    /// anchor still clearly belongs to the display where the compact bubble
+    /// lives. Using the panel center here can move the bubble to the neighbor.
+    static func presentationVisibleFrame(for windowFrame: NSRect, among visibleFrames: [NSRect]) -> NSRect? {
+        guard !visibleFrames.isEmpty else { return nil }
+        let anchor = topTrailingAnchor(for: windowFrame)
+        return visibleFrame(containing: anchor, among: visibleFrames)
+    }
+
+    static func topTrailingAnchor(for frame: NSRect, inset: CGFloat = 1) -> NSPoint {
+        NSPoint(
+            x: max(frame.minX, frame.maxX - inset),
+            y: max(frame.minY, frame.maxY - inset)
+        )
+    }
+
+    static func visibleFrame(containing point: NSPoint, among visibleFrames: [NSRect]) -> NSRect? {
+        guard !visibleFrames.isEmpty else { return nil }
+        if let containing = visibleFrames.first(where: { $0.contains(point) }) {
+            return containing
+        }
+        return visibleFrames.min {
+            distanceSquared(from: point, to: $0) < distanceSquared(from: point, to: $1)
+        }
+    }
+
+    static func clamp(_ origin: NSPoint, windowSize: NSSize, to visibleFrame: NSRect, margin: CGFloat = 0) -> NSPoint {
+        let minX = visibleFrame.minX + margin
+        let maxX = visibleFrame.maxX - windowSize.width - margin
+        let minY = visibleFrame.minY + margin
+        let maxY = visibleFrame.maxY - windowSize.height - margin
+        return NSPoint(
+            x: max(minX, min(origin.x, maxX)),
+            y: max(minY, min(origin.y, maxY))
+        )
+    }
+
+    private static func distanceSquared(from point: NSPoint, to rect: NSRect) -> CGFloat {
+        let x = max(rect.minX, min(point.x, rect.maxX))
+        let y = max(rect.minY, min(point.y, rect.maxY))
+        let dx = point.x - x
+        let dy = point.y - y
+        return dx * dx + dy * dy
+    }
+}