codex-passport-sync 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. codex_passport_sync-0.1.1/.gitignore +32 -0
  2. codex_passport_sync-0.1.1/LICENSE +21 -0
  3. codex_passport_sync-0.1.1/PKG-INFO +105 -0
  4. codex_passport_sync-0.1.1/README.md +88 -0
  5. codex_passport_sync-0.1.1/README.zh_CN.md +81 -0
  6. codex_passport_sync-0.1.1/THIRD_PARTY.md +45 -0
  7. codex_passport_sync-0.1.1/android/app/src/main/AndroidManifest.xml +21 -0
  8. codex_passport_sync-0.1.1/android/app/src/main/java/dev/passport/codex/MainActivity.java +241 -0
  9. codex_passport_sync-0.1.1/android/app/src/main/java/dev/passport/codex/RelayService.java +289 -0
  10. codex_passport_sync-0.1.1/android/app/src/main/java/dev/passport/codex/UsagePace.java +17 -0
  11. codex_passport_sync-0.1.1/android/app/src/main/res/drawable/ic_arrow.xml +1 -0
  12. codex_passport_sync-0.1.1/android/app/src/main/res/drawable/ic_check.xml +1 -0
  13. codex_passport_sync-0.1.1/android/app/src/main/res/drawable/ic_home.xml +1 -0
  14. codex_passport_sync-0.1.1/android/app/src/main/res/drawable/ic_inbox.xml +1 -0
  15. codex_passport_sync-0.1.1/android/app/src/main/res/drawable/ic_link.xml +1 -0
  16. codex_passport_sync-0.1.1/android/app/src/main/res/drawable/ic_passport.xml +1 -0
  17. codex_passport_sync-0.1.1/android/app/src/main/res/drawable/ic_pause.xml +1 -0
  18. codex_passport_sync-0.1.1/android/app/src/main/res/values/colors.xml +14 -0
  19. codex_passport_sync-0.1.1/android/app/src/main/res/values/styles.xml +14 -0
  20. codex_passport_sync-0.1.1/android/app/src/main/res/values-night/colors.xml +14 -0
  21. codex_passport_sync-0.1.1/docs/DEVELOPMENT.md +71 -0
  22. codex_passport_sync-0.1.1/docs/GETTING_STARTED.zh_CN.md +304 -0
  23. codex_passport_sync-0.1.1/docs/PYTHON.md +128 -0
  24. codex_passport_sync-0.1.1/docs/THIRD_PARTY_NOTICES.txt +2577 -0
  25. codex_passport_sync-0.1.1/docs/VALIDATION.md +61 -0
  26. codex_passport_sync-0.1.1/docs/images/dashboard-example.png +0 -0
  27. codex_passport_sync-0.1.1/pyproject.toml +34 -0
  28. codex_passport_sync-0.1.1/src/codex_passport/__init__.py +2 -0
  29. codex_passport_sync-0.1.1/src/codex_passport/__main__.py +2 -0
  30. codex_passport_sync-0.1.1/src/codex_passport/ble.py +127 -0
  31. codex_passport_sync-0.1.1/src/codex_passport/cli.py +270 -0
  32. codex_passport_sync-0.1.1/src/codex_passport/relay.py +133 -0
  33. codex_passport_sync-0.1.1/src/codex_passport/routing.py +46 -0
  34. codex_passport_sync-0.1.1/src/codex_passport/sessions.py +155 -0
  35. codex_passport_sync-0.1.1/src/codex_passport/store.py +198 -0
  36. codex_passport_sync-0.1.1/src/codex_passport/usage.py +87 -0
  37. codex_passport_sync-0.1.1/tests/UsagePaceTest.java +12 -0
  38. codex_passport_sync-0.1.1/tests/test_ble.py +61 -0
  39. codex_passport_sync-0.1.1/tests/test_controls.c +17 -0
  40. codex_passport_sync-0.1.1/tests/test_protocol.c +29 -0
  41. codex_passport_sync-0.1.1/tests/test_sync.py +148 -0
@@ -0,0 +1,32 @@
1
+ upstream/
2
+ .toolchains/
3
+ .runtime/
4
+ .venv/
5
+ __pycache__/
6
+ *.pyc
7
+ firmware/build/
8
+ firmware/managed_components/
9
+ firmware/sdkconfig*
10
+ !firmware/sdkconfig.defaults
11
+ dist/
12
+
13
+ android/local.properties
14
+ android/.gradle/
15
+ android/build/
16
+ android/app/build/
17
+
18
+ # Generated or private deployment material
19
+ artifacts/
20
+ .DS_Store
21
+ *.jks
22
+ *.keystore
23
+ *.pem
24
+ *.key
25
+ .env
26
+ .env.*
27
+ *.sqlite*
28
+ *.db*
29
+ *.log
30
+
31
+ # User-downloaded release files
32
+ downloads/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Codex Passport contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,105 @@
1
+ Metadata-Version: 2.5
2
+ Name: codex-passport-sync
3
+ Version: 0.1.1
4
+ Summary: Local Codex lifecycle notifications and usage for FoloToy AI Passport
5
+ Project-URL: Homepage, https://github.com/JuneLeGency/codex-passport
6
+ Project-URL: Documentation, https://github.com/JuneLeGency/codex-passport/blob/main/docs/GETTING_STARTED.zh_CN.md
7
+ Project-URL: Repository, https://github.com/JuneLeGency/codex-passport
8
+ Project-URL: Issues, https://github.com/JuneLeGency/codex-passport/issues
9
+ Project-URL: Changelog, https://github.com/JuneLeGency/codex-passport/releases
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Requires-Python: >=3.10
13
+ Requires-Dist: pyserial<4,>=3.5
14
+ Provides-Extra: ble
15
+ Requires-Dist: bleak<4,>=1.1; extra == 'ble'
16
+ Description-Content-Type: text/markdown
17
+
18
+ # Codex Passport
19
+
20
+ Codex session notifications and quota visualization on FoloToy AI Passport, with an Android companion.
21
+
22
+ **[从零开始:中文一步步入门](https://github.com/JuneLeGency/codex-passport/blob/main/docs/GETTING_STARTED.zh_CN.md)** · [中文介绍](https://github.com/JuneLeGency/codex-passport/blob/main/README.zh_CN.md) · [Python / uvx guide](https://github.com/JuneLeGency/codex-passport/blob/main/docs/PYTHON.md) · [Downloads](https://github.com/JuneLeGency/codex-passport/releases)
23
+
24
+ <img src="https://raw.githubusercontent.com/JuneLeGency/codex-passport/main/docs/images/dashboard-example.png" alt="Passport graphical quota dashboard" width="240">
25
+
26
+ Synthetic quota fixture rendered on the physical device; no account or conversation data.
27
+
28
+ ## What it does
29
+
30
+ - Computer → encrypted BLE → Passport, or computer → private LAN/WireGuard → Android → encrypted BLE → Passport.
31
+ - Meaningful completion, failure, interruption, approval and input notifications across local Codex sessions. Starts and housekeeping update silently; internal guardian/memory workers are excluded.
32
+ - Durable delivery queue, device acknowledgements, offline replay, and one active BLE sender with phone fallback.
33
+ - Remaining quota compared with remaining cycle time. Orange means faster consumption, green balanced, blue slower.
34
+ - Native 240×320 Passport dashboard and physical-button controls. Material 3 Expressive Android overview, notification and connection pages.
35
+
36
+ Phone notifications show bounded titles and summaries for the four most recent sessions. Passport receives quota, counts and receipt IDs, with no conversation text.
37
+ **This version does not resume conversations, send replies or approve actions.** Those stay in Codex.
38
+ Hooks need existing sessions to restart after installation; incremental logs are a compatibility fallback, not a stable API or Codex Mobile push integration.
39
+ Other computers need their own collectors.
40
+
41
+ ## Get started
42
+
43
+ The [beginner guide](https://github.com/JuneLeGency/codex-passport/blob/main/docs/GETTING_STARTED.zh_CN.md) covers tool installation, backup/app-only flashing, APK installation without ADB, relay configuration, pairing, a real notification test, startup, switching, troubleshooting and removal.
44
+ It uses the verified macOS + Android + Passport setup. Linux host deployment needs platform adaptation; Windows host deployment has not been validated.
45
+
46
+ Download the ready-made [Android APK and Passport firmware v0.1.0](https://github.com/JuneLeGency/codex-passport/releases/tag/v0.1.0).
47
+ Python 0.1.1 is a documentation/packaging update compatible with those device files; no device reinstall is needed for this update.
48
+ The APK is debug-signed. Back up the device before flashing and write **only the app at 0x10000 on the documented hardware layout**, preserving its other partitions.
49
+
50
+ ## Python installation
51
+
52
+ Requires Python 3.10+ and a working, logged-in Codex CLI. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then try:
53
+
54
+ ```sh
55
+ uvx --from 'codex-passport-sync==0.1.1' codex-passport --help
56
+ ```
57
+
58
+ For persistent hooks, install a persistent tool environment instead:
59
+
60
+ ```sh
61
+ uv tool install 'codex-passport-sync[ble]==0.1.1'
62
+ uv tool update-shell
63
+ ```
64
+
65
+ Open a new terminal, then:
66
+
67
+ ```sh
68
+ codex-passport install-hooks
69
+ export COMPUTER_LAN_IP="replace-with-this-computers-private-IP"
70
+ codex-passport serve --host "$COMPUTER_LAN_IP" --port 18765
71
+ ```
72
+
73
+ Keep that terminal open. Configure Android's Connection page with `http://YOUR_COMPUTER_IP:18765` and the contents of `~/.local/state/codex-passport/relay-token`.
74
+ Allow Bluetooth permissions and enter the current six-digit Passport code in the phone's system pairing dialog.
75
+ Restart existing Codex sessions to load the hooks. The address is the relay API, not wireless ADB or a WireGuard endpoint.
76
+
77
+ Add `--ble "Passport-XXXXXX"` using your device's actual advertised name for computer BLE. First pairing requires the computer's OS dialog and Bluetooth permission.
78
+ The `[ble]` extra is required for this route. Select the sender on Android's Connection page; a failed computer connection falls back to the phone and stays there until selected again.
79
+ Do not install permanent hooks from a temporary uvx environment, whose cache can be removed.
80
+
81
+ [PyPI package](https://pypi.org/project/codex-passport-sync/) · [Wheel downloads](https://github.com/JuneLeGency/codex-passport/releases/tag/v0.1.1) · [All installation options and state paths](https://github.com/JuneLeGency/codex-passport/blob/main/docs/PYTHON.md)
82
+
83
+ ## Daily controls and scope
84
+
85
+ | Control | Result |
86
+ | --- | --- |
87
+ | UP / DOWN | Switch quota windows |
88
+ | Short OK while awake | Mark received notifications read; never approve an action |
89
+ | First press while asleep | Wake only |
90
+ | Hold OK while awake | Reconnect BLE, preserving bonds |
91
+
92
+ The backlight sleeps after 60 seconds without alerts/buttons. Daily BLE frames contain no conversation text.
93
+ An authenticated private relay and paired BLE protect access; bounded phone summaries can still contain private context.
94
+ Keep the relay within your private network/VPN. Do not expose its HTTP port publicly. The computer must stay awake and run the collector.
95
+
96
+ Both BLE routes, route switching, replay and physical controls were validated. Off-LAN WireGuard and battery endurance were not measured.
97
+ See the [validation record](https://github.com/JuneLeGency/codex-passport/blob/main/docs/VALIDATION.md) for the exact evidence and limitations.
98
+
99
+ ## Development and attribution
100
+
101
+ [Build instructions](https://github.com/JuneLeGency/codex-passport/blob/main/docs/DEVELOPMENT.md) · [MIT license](https://github.com/JuneLeGency/codex-passport/blob/main/LICENSE) · [Third-party notices](https://github.com/JuneLeGency/codex-passport/blob/main/THIRD_PARTY.md)
102
+
103
+ Application code is independently authored. Official FoloToy BSP, Material Components and other dependencies retain their own licenses.
104
+ The [reference application](https://github.com/zt20/codex-usage-ai-passport) was studied, not copied.
105
+ This is a community project, not an official OpenAI or FoloToy product.
@@ -0,0 +1,88 @@
1
+ # Codex Passport
2
+
3
+ Codex session notifications and quota visualization on FoloToy AI Passport, with an Android companion.
4
+
5
+ **[从零开始:中文一步步入门](https://github.com/JuneLeGency/codex-passport/blob/main/docs/GETTING_STARTED.zh_CN.md)** · [中文介绍](https://github.com/JuneLeGency/codex-passport/blob/main/README.zh_CN.md) · [Python / uvx guide](https://github.com/JuneLeGency/codex-passport/blob/main/docs/PYTHON.md) · [Downloads](https://github.com/JuneLeGency/codex-passport/releases)
6
+
7
+ <img src="https://raw.githubusercontent.com/JuneLeGency/codex-passport/main/docs/images/dashboard-example.png" alt="Passport graphical quota dashboard" width="240">
8
+
9
+ Synthetic quota fixture rendered on the physical device; no account or conversation data.
10
+
11
+ ## What it does
12
+
13
+ - Computer → encrypted BLE → Passport, or computer → private LAN/WireGuard → Android → encrypted BLE → Passport.
14
+ - Meaningful completion, failure, interruption, approval and input notifications across local Codex sessions. Starts and housekeeping update silently; internal guardian/memory workers are excluded.
15
+ - Durable delivery queue, device acknowledgements, offline replay, and one active BLE sender with phone fallback.
16
+ - Remaining quota compared with remaining cycle time. Orange means faster consumption, green balanced, blue slower.
17
+ - Native 240×320 Passport dashboard and physical-button controls. Material 3 Expressive Android overview, notification and connection pages.
18
+
19
+ Phone notifications show bounded titles and summaries for the four most recent sessions. Passport receives quota, counts and receipt IDs, with no conversation text.
20
+ **This version does not resume conversations, send replies or approve actions.** Those stay in Codex.
21
+ Hooks need existing sessions to restart after installation; incremental logs are a compatibility fallback, not a stable API or Codex Mobile push integration.
22
+ Other computers need their own collectors.
23
+
24
+ ## Get started
25
+
26
+ The [beginner guide](https://github.com/JuneLeGency/codex-passport/blob/main/docs/GETTING_STARTED.zh_CN.md) covers tool installation, backup/app-only flashing, APK installation without ADB, relay configuration, pairing, a real notification test, startup, switching, troubleshooting and removal.
27
+ It uses the verified macOS + Android + Passport setup. Linux host deployment needs platform adaptation; Windows host deployment has not been validated.
28
+
29
+ Download the ready-made [Android APK and Passport firmware v0.1.0](https://github.com/JuneLeGency/codex-passport/releases/tag/v0.1.0).
30
+ Python 0.1.1 is a documentation/packaging update compatible with those device files; no device reinstall is needed for this update.
31
+ The APK is debug-signed. Back up the device before flashing and write **only the app at 0x10000 on the documented hardware layout**, preserving its other partitions.
32
+
33
+ ## Python installation
34
+
35
+ Requires Python 3.10+ and a working, logged-in Codex CLI. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then try:
36
+
37
+ ```sh
38
+ uvx --from 'codex-passport-sync==0.1.1' codex-passport --help
39
+ ```
40
+
41
+ For persistent hooks, install a persistent tool environment instead:
42
+
43
+ ```sh
44
+ uv tool install 'codex-passport-sync[ble]==0.1.1'
45
+ uv tool update-shell
46
+ ```
47
+
48
+ Open a new terminal, then:
49
+
50
+ ```sh
51
+ codex-passport install-hooks
52
+ export COMPUTER_LAN_IP="replace-with-this-computers-private-IP"
53
+ codex-passport serve --host "$COMPUTER_LAN_IP" --port 18765
54
+ ```
55
+
56
+ Keep that terminal open. Configure Android's Connection page with `http://YOUR_COMPUTER_IP:18765` and the contents of `~/.local/state/codex-passport/relay-token`.
57
+ Allow Bluetooth permissions and enter the current six-digit Passport code in the phone's system pairing dialog.
58
+ Restart existing Codex sessions to load the hooks. The address is the relay API, not wireless ADB or a WireGuard endpoint.
59
+
60
+ Add `--ble "Passport-XXXXXX"` using your device's actual advertised name for computer BLE. First pairing requires the computer's OS dialog and Bluetooth permission.
61
+ The `[ble]` extra is required for this route. Select the sender on Android's Connection page; a failed computer connection falls back to the phone and stays there until selected again.
62
+ Do not install permanent hooks from a temporary uvx environment, whose cache can be removed.
63
+
64
+ [PyPI package](https://pypi.org/project/codex-passport-sync/) · [Wheel downloads](https://github.com/JuneLeGency/codex-passport/releases/tag/v0.1.1) · [All installation options and state paths](https://github.com/JuneLeGency/codex-passport/blob/main/docs/PYTHON.md)
65
+
66
+ ## Daily controls and scope
67
+
68
+ | Control | Result |
69
+ | --- | --- |
70
+ | UP / DOWN | Switch quota windows |
71
+ | Short OK while awake | Mark received notifications read; never approve an action |
72
+ | First press while asleep | Wake only |
73
+ | Hold OK while awake | Reconnect BLE, preserving bonds |
74
+
75
+ The backlight sleeps after 60 seconds without alerts/buttons. Daily BLE frames contain no conversation text.
76
+ An authenticated private relay and paired BLE protect access; bounded phone summaries can still contain private context.
77
+ Keep the relay within your private network/VPN. Do not expose its HTTP port publicly. The computer must stay awake and run the collector.
78
+
79
+ Both BLE routes, route switching, replay and physical controls were validated. Off-LAN WireGuard and battery endurance were not measured.
80
+ See the [validation record](https://github.com/JuneLeGency/codex-passport/blob/main/docs/VALIDATION.md) for the exact evidence and limitations.
81
+
82
+ ## Development and attribution
83
+
84
+ [Build instructions](https://github.com/JuneLeGency/codex-passport/blob/main/docs/DEVELOPMENT.md) · [MIT license](https://github.com/JuneLeGency/codex-passport/blob/main/LICENSE) · [Third-party notices](https://github.com/JuneLeGency/codex-passport/blob/main/THIRD_PARTY.md)
85
+
86
+ Application code is independently authored. Official FoloToy BSP, Material Components and other dependencies retain their own licenses.
87
+ The [reference application](https://github.com/zt20/codex-usage-ai-passport) was studied, not copied.
88
+ This is a community project, not an official OpenAI or FoloToy product.
@@ -0,0 +1,81 @@
1
+ # Codex Passport
2
+
3
+ 把 Codex 会话通知和账户用量同步到 FoloToy AI Passport,搭配 Android 手机使用。
4
+
5
+ **[第一次使用?从这里一步步安装](docs/GETTING_STARTED.zh_CN.md)** · [Python / uvx 安装](docs/PYTHON.md) · [下载 APK 和固件](https://github.com/JuneLeGency/codex-passport/releases/tag/v0.1.0) · [English](README.md)
6
+
7
+ <img src="docs/images/dashboard-example.png" alt="Passport 用量环形仪表" width="240">
8
+
9
+ 设备实机渲染的合成示例,不包含账号用量或会话内容。
10
+
11
+ ## 能做什么
12
+
13
+ - 电脑直接通过加密 BLE 发送到 Passport,或通过局域网/WireGuard 交给 Android 再转发 BLE。
14
+ - 本机各 Codex 会话的完成、失败、中断、需批准和等待输入提醒;开始、会话生命周期和压缩等状态静默更新,过滤内部 guardian 与记忆整理任务。
15
+ - 消息持久化、去重、设备回执和断线补送;两条 BLE 路径共享队列,一次只由一个发送方连接。
16
+ - 将本周期剩余额度与剩余时间对比,直观看到消耗偏快、均衡或偏慢。
17
+ - 原生 Passport 小屏图形与实体按键;Android 使用 Material 3 Expressive,提供概览、通知、连接三页。
18
+
19
+ 手机显示最近四个会话的短标题和摘要;标题最多 60 UTF-8 字节、摘要最多 120 字节,不是完整上下文。
20
+ Passport 日常只接收用量、计数和回执 ID,不传会话标题、摘要或项目名。
21
+ **本版不支持手机恢复会话、回复问题或人工批准操作**;这些仍在 Codex 完成。OK 标记已读不代表批准。
22
+
23
+ ## 新手从哪里开始
24
+
25
+ [从零入门指南](docs/GETTING_STARTED.zh_CN.md) 按顺序覆盖:
26
+
27
+ 1. 准备设备、安装 uv、下载项目。
28
+ 2. 备份 Passport,只烧录应用分区。
29
+ 3. 手机直接下载 APK 安装,无需 Android Studio 或无线 ADB。
30
+ 4. 查电脑 IP、安装 Hooks、启动中继、填写手机地址与密钥。
31
+ 5. 用 Passport 当前六位码完成配对,再用真实 Codex 通知验收。
32
+ 6. 看懂用量图和按键,配置登录自启动、电脑直连与手机转发。
33
+ 7. 排查常见问题,更新、暂停和卸载。
34
+
35
+ 指南以实测的 **macOS + Android + AI Passport** 为主,不限电脑机型。Linux 需适配系统服务和蓝牙;Windows 主机未完成验收,不能直接照抄本指南的 shell 命令。
36
+
37
+ ## 版本与安装文件
38
+
39
+ | 文件 | 用途 |
40
+ | --- | --- |
41
+ | [Python `codex-passport-sync` 0.1.1](https://pypi.org/project/codex-passport-sync/) | 电脑采集器和中继;本次更新使用指南、包信息和发布方式 |
42
+ | [Android APK 0.1.0](https://github.com/JuneLeGency/codex-passport/releases/tag/v0.1.0) | 手机伴侣;调试签名,尚未上架应用商店 |
43
+ | [Passport 固件 0.1.0](https://github.com/JuneLeGency/codex-passport/releases/tag/v0.1.0) | 设备上的图形仪表;只烧录到官方布局的应用分区 `0x10000` |
44
+
45
+ Python 0.1.1 与已有 APK/固件兼容,本次无需重新安装设备端。发布页同时提供 SHA256 校验和第三方许可证。
46
+ 如果只想先查看 Python 命令,在安装 uv 后运行:
47
+
48
+ ```sh
49
+ uvx --from 'codex-passport-sync==0.1.1' codex-passport --help
50
+ ```
51
+
52
+ 日常 Hooks 和自启动需要持久环境,按 [Python 安装指南](docs/PYTHON.md) 或从零指南安装,不要把长期 Hooks 绑定到临时 uvx 缓存。
53
+
54
+ ## 日常使用
55
+
56
+ Passport 外环是剩余额度,内环是剩余时间。橙色表示消耗领先时间超过 5 个百分点,绿色表示基本同步,蓝色表示较慢;周期最初 1% 暂不判断快慢。
57
+ 这是当前消耗进度的比较,不是未来用量预测。接口无返回、额度过期或超过 180 秒未更新时显示不可用,不编造满额。
58
+
59
+ 上/下键切换周期;亮屏时短按 OK 标记已读;长按 OK 重连并保留配对。
60
+ 熄屏后第一次按键只唤醒,不清未读。60 秒无提醒/按键后熄屏,新提醒会亮屏。屏幕不支持触控。
61
+
62
+ 离开电脑时,在手机“连接”页选择“使用手机转发”。电脑连接失败也会回退到手机,回退后不会反复抢连接;回到电脑旁可主动切回直连。
63
+ 外出需要你自己的 WireGuard 路由能访问电脑中继。电脑保持开机和中继运行,手机与 Passport 保持 BLE 可达。
64
+
65
+ ## 数据与验收边界
66
+
67
+ Hooks 安装后需要重新打开已有 Codex 会话;增量日志是兼容性补偿,格式不是稳定 API。
68
+ 本项目没有接入 Codex Mobile 私有推送服务,不保证逐项等价。其他电脑的会话需在对应主机采集。
69
+
70
+ 手机摘要仍可能含私人内容,只给自己的手机配置专用密钥。完整对话和原始命令不转发,常见凭据模式会脱敏,但不要因此把中继或摘要公开。
71
+ HTTP 中继仅供私有网络/VPN 使用,不直接暴露公网。原始 Flash 备份、状态目录和密钥不属于开源发布内容。
72
+
73
+ 电脑直连、手机转发、切换补送和实体按键已通过验收;外网 WireGuard 按本次发布范围未做实测,未测量电流与续航。
74
+ 详细证据见 [验证记录](docs/VALIDATION.md)。
75
+
76
+ ## 开发与参考
77
+
78
+ [构建与开发](docs/DEVELOPMENT.md) · [MIT 许可证](LICENSE) · [第三方依赖与许可](THIRD_PARTY.md)
79
+
80
+ 应用代码独立编写。官方 [FoloToy BSP](https://github.com/folotoy/ai-passport) 为单独获取的依赖;[参考应用](https://github.com/zt20/codex-usage-ai-passport) 仅研究,不复用实现。
81
+ Android 使用官方 [Material Components](https://github.com/material-components/material-components-android/releases/tag/1.14.0)。本项目是社区作品,不代表 OpenAI 或 FoloToy 官方产品。
@@ -0,0 +1,45 @@
1
+ # Third-party dependencies
2
+
3
+ Application code in `src/`, `firmware/main/`, `android/` and `scripts/` is independently authored.
4
+ Dependencies are fetched separately and retain their own licenses.
5
+
6
+ | Dependency | Purpose | License |
7
+ | --- | --- | --- |
8
+ | [FoloToy AI Passport](https://github.com/folotoy/ai-passport/tree/f75873f1aab24ac4c0ba9394c131669f66cce650) | Hardware BSP | MIT, © 2026 FoloToy |
9
+ | [ESP-IDF](https://github.com/espressif/esp-idf/tree/v5.5.3) | ESP32 runtime and drivers | Apache-2.0, with component-specific notices |
10
+ | [LVGL](https://github.com/lvgl/lvgl) | Device graphics and bundled fonts/icons | MIT; retain bundled asset notices |
11
+ | [Material Components Android](https://github.com/material-components/material-components-android/tree/1.14.0) | Native M3 Expressive components | Apache-2.0 |
12
+ | [AndroidX](https://developer.android.com/jetpack/androidx) | Android UI compatibility | Apache-2.0 |
13
+ | [Bleak](https://github.com/hbldh/bleak) | Computer BLE client | MIT |
14
+ | [pySerial](https://github.com/pyserial/pyserial) | Optional USB diagnostics | BSD-3-Clause |
15
+
16
+ Transitive dependencies and exact ESP component hashes are recorded in the dependency locks.
17
+ Full bundled-runtime notices are included in [THIRD_PARTY_NOTICES.txt](docs/THIRD_PARTY_NOTICES.txt).
18
+ Distributors of built firmware/APKs must retain applicable third-party notices.
19
+ The studied [Codex Usage AI Passport](https://github.com/zt20/codex-usage-ai-passport) application
20
+ is a reference only: its implementation is not included or copied.
21
+ This is an independent community project, not an official OpenAI or FoloToy product.
22
+
23
+ ## FoloToy BSP license
24
+
25
+ MIT License
26
+
27
+ Copyright (c) 2026 FoloToy
28
+
29
+ Permission is hereby granted, free of charge, to any person obtaining a copy
30
+ of this software and associated documentation files (the "Software"), to deal
31
+ in the Software without restriction, including without limitation the rights
32
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
33
+ copies of the Software, and to permit persons to whom the Software is
34
+ furnished to do so, subject to the following conditions:
35
+
36
+ The above copyright notice and this permission notice shall be included in all
37
+ copies or substantial portions of the Software.
38
+
39
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
40
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
41
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
42
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
43
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
44
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
45
+ SOFTWARE.
@@ -0,0 +1,21 @@
1
+ <manifest xmlns:android="http://schemas.android.com/apk/res/android">
2
+ <uses-permission android:name="android.permission.INTERNET"/>
3
+ <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
4
+ <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/>
5
+ <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
6
+ <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30"/>
7
+ <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation"/>
8
+ <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
9
+ <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
10
+ <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
11
+ <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE"/>
12
+ <uses-permission android:name="android.permission.WAKE_LOCK"/>
13
+ <uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
14
+ <application android:label="Codex Passport" android:theme="@style/Theme.Passport"
15
+ android:icon="@drawable/ic_passport" android:allowBackup="false" android:usesCleartextTraffic="true" android:supportsRtl="true">
16
+ <activity android:name=".MainActivity" android:exported="true">
17
+ <intent-filter><action android:name="android.intent.action.MAIN"/><category android:name="android.intent.category.LAUNCHER"/></intent-filter>
18
+ </activity>
19
+ <service android:name=".RelayService" android:exported="false" android:foregroundServiceType="connectedDevice"/>
20
+ </application>
21
+ </manifest>