@zieglar/pi-chat-exchange 0.2.0 → 0.2.2

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 (43) hide show
  1. package/README.md +41 -61
  2. package/dist/bin/ce-native.js +119 -0
  3. package/dist/control/mcp/server.js +1 -1
  4. package/dist/host/mcp-binding-config.js +1 -1
  5. package/dist/runtime/diagnostics.js +3 -3
  6. package/dist/runtime/executables.js +37 -30
  7. package/dist/runtime/native-readiness.js +131 -0
  8. package/dist/runtime/wrapper-identity.js +53 -0
  9. package/dist/storage/connection.js +4 -3
  10. package/dist/storage/filesystem.js +58 -3
  11. package/dist/storage/native-artifact.js +234 -0
  12. package/dist/storage/native-compat.js +65 -0
  13. package/dist/storage/runtime.js +201 -58
  14. package/dist/storage/sqlite-driver-node.js +66 -0
  15. package/dist/storage/sqlite-driver-rust.js +121 -0
  16. package/dist/storage/sqlite-driver-selection.js +86 -0
  17. package/dist/storage/sqlite-driver.js +4 -0
  18. package/dist/storage/store.js +3 -3
  19. package/dist/storage/transaction.js +20 -23
  20. package/dist/tunnel/background-manager.js +5 -52
  21. package/dist/tunnel/codes.js +1 -1
  22. package/dist/tunnel/keychain.js +1 -1
  23. package/dist/tunnel/managed-binding.js +1 -1
  24. package/dist/tunnel/manager-panel.js +1 -1
  25. package/dist/tunnel/profile.js +4 -2
  26. package/dist/tunnel/setup-ui.js +3 -3
  27. package/dist/tunnel/tunnel-id.js +4 -0
  28. package/package.json +8 -20
  29. package/pi-extension/index.ts +34 -0
  30. package/CHANGELOG.md +0 -70
  31. package/docs/architecture.md +0 -170
  32. package/docs/chatgpt-installation.md +0 -149
  33. package/docs/delivery-ack-contract.md +0 -86
  34. package/docs/independent-install.md +0 -156
  35. package/docs/multi-session-usage.md +0 -77
  36. package/docs/ownership-contract.md +0 -429
  37. package/docs/protocol-v2.md +0 -269
  38. package/docs/releases/0.2.0.md +0 -59
  39. package/docs/storage-contract.md +0 -1241
  40. package/docs/storage-security.md +0 -138
  41. package/docs/tunnel-manager-background.md +0 -169
  42. package/docs/tunnel-setup.md +0 -214
  43. package/pi-extension/README.md +0 -125
package/README.md CHANGED
@@ -1,90 +1,70 @@
1
1
  # Pi Chat Exchange
2
2
 
3
- 让 ChatGPT 与 Pi 通过显式工具交换持久化消息:发送、发现收件箱、授权读取,以及独立授权的接收回执(ACK)。它不是自动任务调度器,也不把 ACK 或对话回复当作任务完成。
3
+ English | [简体中文](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/README.zh-CN.md)
4
4
 
5
- 本包版本为 **0.2.0**。CE 自有代码已获所有者授权采用 **MIT**(见 [LICENSE](LICENSE));第三方许可证证据已按三层证据闭合(逐版本审计记录为 `docs/license-audit.md`,仅仓库保留、不随 tarball 分发)。0.2.0 的认证范围仅 **Node 24.21.0 / Pi 1.3.0 / macOS arm64**;cloud transport 为 NOT_VERIFIED,Linux 未验证。
5
+ Pi Chat Exchange (CE) lets ChatGPT and Pi exchange durable messages through explicit tools. Use it to pass a question, plan or result between the two applications while choosing which messages each side may read. Sending a message does not authorize a task or prove completion.
6
6
 
7
- ## 当前能力与典型用法
7
+ <a id="当前能力与典型用法"></a>
8
8
 
9
- - **持久化消息**:ChatGPT 发来计划或问题,Pi 显式查看 inbox、授权读取,再以新 Message 回复检查结果。
10
- - **独立接收回执**:按需授权 payload read 与 ACK;接收回执不等于任务完成,也不触发正文执行。
11
- - **多 Session**:多个项目中的真实 Pi Session 使用独立 Endpoint,共享 Tunnel;ChatGPT inbox 仍不隔离对话。
9
+ ## Features
12
10
 
13
- 当前不提供自动任务调度、自动执行或 exactly-once delivery/execution。只需自动远端执行而不逐次授权时,本项目不适用。
11
+ - SQLite-backed messages, scoped idempotency keys and audit evidence.
12
+ - Authorized inbox discovery, separate metadata/payload access, and optional reception receipts (ACKs).
13
+ - Explicit Pi Session binding and multi-session registration.
14
+ - Secure MCP Tunnel management and a separate ChatGPT Desktop stdio connection.
15
+ - Rust Native SQLite with pinned trust and explicit installation/readiness commands.
14
16
 
15
- ## 选择连接方式
17
+ ## Requirements and support
16
18
 
17
- - **推荐:Secure MCP Tunnel。** `/ce-tunnel` 提供设置向导、显式激活、后台 Start/Stop 和健康状态;无需 Desktop stdio 插件。按 [Tunnel 快速开始](docs/tunnel-setup.md)操作。
18
- - **Desktop 本地 stdio 插件。** 由支持本地插件的 ChatGPT Desktop 启动 bundled MCP server;需配置本机 Node 与外置 binding。见 [ChatGPT 安装](docs/chatgpt-installation.md)。不要与 Tunnel 同时争用同一 Endpoint。
19
+ Use **Pi 1.3.0**, **Node >=22.19.0** and a Store-supported platform: **macOS arm64 or Linux x64 GNU**. Filesystem, ownership and runtime admission checks still apply. Other Native artifacts do not establish Store support; Windows Native is unsupported and WSL2 integration remains unverified.
19
20
 
20
- ## 安装 Pi 扩展
21
+ Version **0.2.1** is published on npm. An actual Registry installation passed isolated Pi 1.3.0 / Node 22.19.0 loading and persistence checks on macOS arm64. Linux x64 Native checks passed 227/227 on Node 22.19.0 and 24.22.2. **Real Cloud transport and the complete ChatGPT ↔ Pi exchange remain unverified.** See [runtime support](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/runtime-support.md) for the tested matrix and limits; the engine range is not exhaustive qualification.
21
22
 
22
- **信任提示:Pi 扩展以你的完整用户权限运行。安装前审查源码与制品来源;消息授权门槛不等于操作系统沙箱。**
23
+ This working tree prepares local candidate **0.2.2**. Explicit `CE_TUNNEL_CLIENT_PATH` delegates trust to a user-managed client installation, including group-writable Homebrew ancestors; automatic discovery stays strict. Installation writers may replace a program that can run as you and read Tunnel credentials. Install the candidate tarball with npm into a dedicated prefix, then register the installed package directory with Pi; see Getting started. This is not a Registry installation. The npm command below still selects published 0.2.1 and its old admission rules.
23
24
 
24
- 正式日常使用请用**独立安装路径**:作者交付预构建私有 tarball,消费者物理安装后 `pi install` 注册,无需仓库/build,见 [独立安装指南](docs/independent-install.md)。下面是开发者源码路径。
25
+ Candidate evidence: [compatibility matrix](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/compatibility/README.md). Client 0.0.19 has source-matched macOS arm64 legacy-identity manual bidirectional Cloud E2E; Linux x64 CI covers synthetic local lifecycle. Historical 0.0.16 evidence is runtime-scoped; 0.0.18 and real namespaced Cloud remain NOT_VERIFIED. Independent latest monitoring and actual same-run publication integration remain NOT_VERIFIED. Managed profiles explicitly set `MCP_STDIO_FAILURE_POLICY=exit`: on 0.0.19 child failure the client exits, with no automatic respawn or recovery; inspect ownership and recover explicitly before restarting.
25
26
 
26
- 先安装 Pi **1.3.0**、pnpm **12.9.1** 和批准的 Node **24.21.0 或 24.22.1**。Node 还必须通过完整 SQLite 身份、编译选项与 API 门槛,不是任意 `24.x`。Pi host 与 MCP child 分别校验;mise 或其他版本管理器均不是必需品。
27
+ <a id="安装-pi-扩展"></a>
28
+ <a id="选择连接方式"></a>
27
29
 
28
- 从仓库根目录,在已选中批准 Node 的 shell 中执行:
30
+ ## Quick start
29
31
 
30
- ```sh
31
- node --version
32
- pnpm install --frozen-lockfile
33
- pnpm --dir packages/pi-chat-exchange run build
34
- pi -e ./packages/pi-chat-exchange/pi-extension/index.ts
35
- ```
36
-
37
- 扩展入口会导入包内 `dist/`;修改源码后须重新运行上述 build,再在已加载的 Session 中 `/reload`。`/reload` 不会编译源码,旧 `dist/` 会继续运行旧逻辑。
38
-
39
- 这是临时加载。若要长期从不同项目使用,在 build 后执行 `pi install /absolute/path/to/packages/pi-chat-exchange` 注册本地包,再正常启动 Pi。本地安装引用该目录,不复制源码;不要同时安装和 `-e` 加载第二份。本包不提供独立的 `ce` 安装 CLI;安装只经 Pi 的 managed npm / tarball / 本地目录三条路径。
32
+ With Pi already installed, run in your **system terminal**:
40
33
 
41
- 进入交互 TUI 后:
42
-
43
- ```text
44
- /ce-tunnel doctor
45
- /ce-tunnel setup
46
- /reload
47
- /ce-tunnel activate
48
- /ce-status
34
+ ```sh
35
+ pi install npm:@zieglar/pi-chat-exchange@0.2.1
36
+ pi list
37
+ pi
49
38
  ```
50
39
 
51
- Setup 的 Advanced · Messaging 必须显式授权当前 Session;只保存基本 transport 设置时默认不能通信。首次 reload 缺少 mapping 时可能拒绝,随后显式 activate,不清理数据库。启动真实 Tunnel 还需父 Pi 环境的 `CE_TUNNEL_BACKGROUND_ALLOW=1` 和单独 `/ce-tunnel start`;完整步骤、可信绝对路径启动方式和 ChatGPT 自定义 MCP 配置见 [Tunnel 指南](docs/tunnel-setup.md)。
52
-
53
- ## 多项目、多 Session
40
+ In the **Pi TUI**, run `/ce-native status`. If the trusted driver is missing, run `/ce-native install`, then exit and restart Pi. Check `/ce-native verify` reports `READY` before messaging. Native binaries are not bundled in npm; CE never downloads them automatically or falls back to `node:sqlite`.
54
41
 
55
- 每个真实 Pi Session 注册不同的稳定 Endpoint;项目目录本身不是身份。共享的 `chatgpt/main` inbox **不是 ChatGPT 对话隔离**。
42
+ Continue with **[Getting started: installation to your first exchange](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/getting-started.md)**. It covers the separately trusted Tunnel client, parent environment, explicit Setup messaging grants, `/reload` → activate → Start, exact recipient labels, payload reads and safe Stop. Setup Save alone does not authorize messaging; activation does not start transport. The [Desktop stdio guide](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/chatgpt-installation.md) describes the separate local connection.
56
43
 
57
- - `/ce-status`:当前 Pi / CE 身份与 Ownership 状态。
58
- - `/ce-tunnel sessions`:经当前运行时授权的、所选配置中 active Endpoint 列表,不证明 MCP 已加载。
59
- - `/ce-tunnel deactivate`:确认后正常解绑当前本地 CE binding,不删注册/历史,也不停止 Tunnel。
60
- - `/ce-tunnel revoke <exact-endpoint>`:撤销注册的后续权限;需先核实 transport STOPPED,不等于正常解绑。
61
- - `/reload`:有效 binding 重新校验并恢复;已正常释放或未绑定的 Session 需要显式 activate。
44
+ Before upgrading an existing installation, stop the owned Tunnel and verify `STOPPED`, release affected local bindings, then exit affected Pi hosts. Preserve the Store and credentials; do not delete ownership or lock files to force an upgrade.
62
45
 
63
- 转换、注册、权限和生效顺序见 [多 Session 使用指南](docs/multi-session-usage.md)。不要直接修改生成文件或删除 Store/Owner 作为排障。
46
+ <a id="多项目多-session"></a>
47
+ <a id="边界与验证"></a>
64
48
 
65
- ## 阅读导航
49
+ ## Limits and safe operation
66
50
 
67
- | 目标 | 文档 |
68
- |---|---|
69
- | **独立安装(正式日常使用,预构建 tarball)** | [独立安装指南](docs/independent-install.md) |
70
- | 首次设置、可信安装诊断、ChatGPT 连接、启动与排障 | [Tunnel 用户指南](docs/tunnel-setup.md) |
71
- | Desktop stdio 打包与本机配置 | [ChatGPT 安装](docs/chatgpt-installation.md) |
72
- | 工具参数、Inbox、payload/ACK、生命周期 | [Pi 扩展指南](pi-extension/README.md) |
73
- | 多项目/Session 注册、解绑、撤销 | [多 Session 使用](docs/multi-session-usage.md) |
74
- | 分层、身份、授权、验证与扩展点 | [架构指南](docs/architecture.md) |
75
- | 后台进程所有权与停止约束 | [后台 Manager](docs/tunnel-manager-background.md) |
76
- | 精确安全契约 | [协议 v2](docs/protocol-v2.md) · [Ownership](docs/ownership-contract.md) · [Storage](docs/storage-contract.md) · [ACK](docs/delivery-ack-contract.md) · [Store 安全边界](docs/storage-security.md) |
51
+ CE does not automatically schedule tasks or drain inboxes. A shared ChatGPT endpoint does not isolate conversations. Payload reads and ACKs require their own grants; payload text is untrusted data and may enter model history.
77
52
 
78
- 独立安装包(tarball)随包分发上表所有文档、CHANGELOG 与本版本 release notes,消费者无需访问仓库即可取得操作与安全契约。仅作者侧的治理与证据记录(如 `docs/license-audit.md`、`docs/runtime-qualification.md` 及各阶段审计记录)仅仓库保留,不进入消费者制品。
53
+ ACK records reception only, not delivery, reading, processing or task completion. CE provides no exactly-once delivery/execution guarantee. `DELIVERY_UNKNOWN != CANCELLED`; missing ACK or timeout does not authorize blind retry or a new-key resend. Keep the original Message ID/key and inspect evidence first.
79
54
 
80
- ## 边界与验证
55
+ Closing Manager or exiting Pi does not stop the detached Tunnel client. Use `/ce-tunnel stop`, then `/ce-tunnel status` to verify `STOPPED`. Keep credentials and capabilities out of messages, screenshots and reports.
81
56
 
82
- **Configured ≠ Pi-bound ≠ Connected ≠ 消息实证。** `CONNECTED` 只证明测得的传输健康;ACK 仅为 reception receipt,不证明 delivery、read、processing 或 task completion。
57
+ <a id="阅读导航"></a>
83
58
 
84
- 不自动启动/重连、接管过期 Owner、排空 Inbox、执行 payload、合并 Store 或重试未知结果。`DELIVERY_UNKNOWN != CANCELLED`。凭据文件不是加密保险箱;不要把 key、capability、正文或完整日志贴入诊断。
59
+ ## Documentation
85
60
 
86
- Store 平台 allowlist 为 macOS arm64 / Linux x64;两种批准 Node 的实测为 macOS arm64,不等于 Linux 或每种 Desktop UI 均已验收。已有本地人工双向消息与 Tunnel 启停验收不替代本次变更的隔离测试,也不证明机器冷启动或所有终端交互。
61
+ - [Native management](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/native-management.md) and [Native SQLite](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/native-sqlite.md).
62
+ - [Tunnel setup and troubleshooting](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/tunnel-setup.md).
63
+ - [Multiple Sessions](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/multi-session-usage.md), [Pi tools](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/pi-extension/README.md) and [ACK contract](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/delivery-ack-contract.md).
64
+ - [Operations / source development](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/operations.md). The prebuilt npm install needs no repository or compiler.
65
+ - [Independent Host / tarball installation](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/independent-install.md), with current0.2.1 alternatives and a separate historical0.2.0 record.
66
+ - [Architecture](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/architecture.md), [storage security](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/storage-security.md) and [bilingual documentation index](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/documentation.md).
87
67
 
88
- 开发检查:从包目录执行 `pnpm run verify`(check → typecheck → build → test → plugin-package test);扩展测试前须 build。证据层次见[架构指南](docs/architecture.md#验证层次)。
68
+ ## License
89
69
 
90
- 许可证:**MIT**,Copyright (c) 2026 zieglar。第三方依赖保留各自许可,不由 CE 的 MIT 重新授权;`@earendil-works/pi-tui@1.3.0` 与 Host peer 的制品未随包附带 LICENSE 文本(上游打包省略;经 registry 制品与上游 v1.3.0 标签根 LICENSE 三层核实为 MIT)。完整逐版本审计记录为 `docs/license-audit.md`(仅仓库保留,不随 tarball 分发)。0.2.0 的认证范围仅 Node 24.21.0 / Pi 1.3.0 / macOS arm64;cloud NOT_VERIFIED,Linux 未验证。见 [0.2.0 release notes](docs/releases/0.2.0.md) 与 [安全卸载/升级/回滚](docs/independent-install.md#5-安全卸载升级与回滚)。
70
+ [MIT](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/LICENSE), Copyright (c) 2026 zieglar. Dependencies retain their own licenses; see the [license audit](https://github.com/zieglar/pi-packages/blob/main/packages/pi-chat-exchange/docs/licenses.md).
@@ -0,0 +1,119 @@
1
+ #!/usr/bin/env node
2
+ import { readFileSync } from "node:fs";
3
+ import { loadVerifiedNativeArtifact, nativeCacheRoot, nativeTarget, prepareNativeArtifact } from "../storage/native-artifact.js";
4
+ import { NATIVE_COMPAT, parseNativeCompat } from "../storage/native-compat.js";
5
+ import { resolve } from "node:path";
6
+ import { defaultDriverSelectionFile, readDriverSelection, writeDriverSelection } from "../storage/sqlite-driver-selection.js";
7
+ function usage() {
8
+ console.error("Usage: ce-native status | prepare [--version X] | select --driver node-sqlite|rust-native [--version X] [--root DIR] [--manifest FILE] [--selection FILE]");
9
+ process.exit(2);
10
+ }
11
+ function readManifest(path) {
12
+ try {
13
+ return parseNativeCompat(JSON.parse(readFileSync(path, "utf8")));
14
+ }
15
+ catch {
16
+ throw Object.assign(new Error(`invalid Native compatibility manifest: ${path}`), { code: "CE_NATIVE_MANIFEST_INVALID" });
17
+ }
18
+ }
19
+ function parse(argv) {
20
+ const [command, ...rest] = argv;
21
+ if (command === undefined)
22
+ usage();
23
+ const args = { command };
24
+ for (let i = 0; i < rest.length; i += 1) {
25
+ const flag = rest[i];
26
+ const value = rest[i + 1];
27
+ if (value === undefined)
28
+ usage();
29
+ if (flag === "--version")
30
+ args.version = value;
31
+ else if (flag === "--root")
32
+ args.root = value;
33
+ else if (flag === "--manifest") {
34
+ args.manifest = readManifest(value);
35
+ args.manifestFile = resolve(value);
36
+ }
37
+ else if (flag === "--selection")
38
+ args.selectionFile = value;
39
+ else if (flag === "--driver")
40
+ args.command = `${command}:${value}`;
41
+ else
42
+ usage();
43
+ i += 1;
44
+ }
45
+ return args;
46
+ }
47
+ function manifestOptions(args, selectionManifestFile) {
48
+ const manifest = args.manifest ?? (selectionManifestFile === undefined ? undefined : readManifest(selectionManifestFile));
49
+ return {
50
+ ...(args.version === undefined ? {} : { version: args.version }),
51
+ ...(args.root === undefined ? {} : { root: args.root }),
52
+ ...(manifest === undefined ? {} : { manifest }),
53
+ };
54
+ }
55
+ function status(args) {
56
+ const selection = readDriverSelection(args.selectionFile);
57
+ const result = {
58
+ selectionFile: args.selectionFile ?? defaultDriverSelectionFile(),
59
+ driver: selection.driver,
60
+ nativeVersion: selection.nativeVersion ?? null,
61
+ target: nativeTarget(),
62
+ cacheRoot: args.root ?? nativeCacheRoot(),
63
+ };
64
+ if (selection.driver === "rust-native") {
65
+ try {
66
+ const verified = loadVerifiedNativeArtifact({ ...(selection.nativeVersion === undefined ? {} : { version: selection.nativeVersion }), ...manifestOptions(args, selection.manifestFile) });
67
+ result.ready = true;
68
+ result.native = verified.info;
69
+ }
70
+ catch (error) {
71
+ result.ready = false;
72
+ result.error = error instanceof Error && "code" in error ? error.code : "CE_NATIVE_LOAD_FAILED";
73
+ }
74
+ }
75
+ else {
76
+ result.ready = true;
77
+ }
78
+ console.log(JSON.stringify(result, null, 2));
79
+ }
80
+ async function main() {
81
+ const args = parse(process.argv.slice(2));
82
+ if (args.command === "status")
83
+ return status(args);
84
+ if (args.command === "prepare") {
85
+ const prepared = await prepareNativeArtifact(manifestOptions(args));
86
+ console.log(JSON.stringify({ prepared: true, path: prepared.path, info: prepared.info }, null, 2));
87
+ return;
88
+ }
89
+ if (args.command.startsWith("select:")) {
90
+ const driver = args.command.slice("select:".length);
91
+ if (driver !== "node-sqlite" && driver !== "rust-native")
92
+ usage();
93
+ const selection = driver === "node-sqlite"
94
+ ? { driver }
95
+ : { driver, nativeVersion: args.version ?? (args.manifest ?? NATIVE_COMPAT).defaultVersion };
96
+ if (driver === "rust-native") {
97
+ if (args.root !== undefined && resolve(args.root) !== nativeCacheRoot()) {
98
+ throw Object.assign(new Error("select requires the default runtime cache root; use --root only for prepare/status qualification"), { code: "CE_NATIVE_SELECTION_ROOT_INVALID" });
99
+ }
100
+ const verified = loadVerifiedNativeArtifact(manifestOptions(args));
101
+ writeDriverSelection({ ...selection, ...(args.manifestFile === undefined ? {} : { manifestFile: args.manifestFile }) }, args.selectionFile);
102
+ console.log(JSON.stringify({ selected: selection, native: verified.info }, null, 2));
103
+ }
104
+ else {
105
+ writeDriverSelection(selection, args.selectionFile);
106
+ console.log(JSON.stringify({ selected: selection }, null, 2));
107
+ }
108
+ return;
109
+ }
110
+ usage();
111
+ }
112
+ try {
113
+ await main();
114
+ }
115
+ catch (error) {
116
+ console.error(error instanceof Error && "code" in error ? `${error.code}: ${error.message}` : String(error));
117
+ process.exitCode = 1;
118
+ }
119
+ //# sourceMappingURL=ce-native.js.map
@@ -23,7 +23,7 @@ import { observeTransport } from "./debug-transport.js";
23
23
  import { PING_TOOL_NAME, PingArgsSchema, PingResultSchema, defaultHostLabel, ping } from "./ping.js";
24
24
  import { callMessagingTool, CE_ACK_TOOL, isAckToolName, isMessagingToolName, MESSAGING_TOOLS, } from "./messaging-tools.js";
25
25
  export const SERVER_NAME = "pi-chat-exchange";
26
- export const SERVER_VERSION = "0.2.0";
26
+ export const SERVER_VERSION = "0.2.2";
27
27
  const PING_TOOL = {
28
28
  name: PING_TOOL_NAME,
29
29
  description: "Read-only liveness probe for the pi-chat-exchange service. " +
@@ -9,6 +9,7 @@
9
9
  * structural field path).
10
10
  */
11
11
  import { isAbsolute, normalize } from "node:path";
12
+ import { TUNNEL_ID_PATTERN as MANAGED_TUNNEL_ID } from "../tunnel/tunnel-id.js";
12
13
  import { LEASE_MAX_TTL_SECONDS, LEASE_MIN_TTL_SECONDS } from "../storage/ownership.js";
13
14
  export const MCP_BINDING_CONFIG_VERSION = 1;
14
15
  export const MCP_DEFAULT_LEASE_TTL_SECONDS = 120;
@@ -138,7 +139,6 @@ function debugExecutionGuardPolicy(value) {
138
139
  throw new McpBindingConfigError("debugExecutionGuard.enabled");
139
140
  return Object.freeze({ enabled: fields.enabled });
140
141
  }
141
- const MANAGED_TUNNEL_ID = /^tunnel_[A-Za-z0-9]{8,}$/;
142
142
  const MANAGED_ORGANIZATION_ID = /^org-[A-Za-z0-9]{1,128}$/;
143
143
  /** Managed provenance is validated with the same label discipline as every
144
144
  * other field: strict identity shapes, no credential-shaped strings. */
@@ -1,4 +1,4 @@
1
- import { APPROVED_RUNTIME_TUPLES, assertHostRuntimeEligibility } from "../storage/runtime.js";
1
+ import { CANDIDATE_NODE_RANGE, MINIMUM_SQLITE_VERSION, PI_HOST_MINIMUM_NODE_VERSION, assertHostRuntimeEligibility } from "../storage/runtime.js";
2
2
  import { ExecutableRefusal, diagnoseTunnelClient, resolveApprovedNode } from "./executables.js";
3
3
  /** No profile, credential, Store or transport access. Host uses the actual
4
4
  * in-memory SQLite/API battery; only an admitted Node child is executed. */
@@ -22,13 +22,13 @@ export function diagnoseInstallation(options = {}) {
22
22
  export function installationDiagnosticMessage(result) {
23
23
  return `ce-tunnel doctor: Pi host=${result.host} (in-memory SQLite/runtime check); MCP child=${result.child}; client=${result.client}. ` +
24
24
  "Client trust is metadata only, not compatibility or connectivity. No client executed; no profile/Store/transport changes. " +
25
- "For a missing client, install separately; for rejected trust, repair the private installation and its ancestors/ACLs or select a trusted absolute CE_TUNNEL_CLIENT_PATH outside projects. Never use PATH fallback or relax trust. " +
25
+ "For a missing client, install separately. CE_TUNNEL_CLIENT_PATH explicitly trusts a user-managed client and permits group-writable ancestors; automatic discovery stays strict. Check the normalized absolute path, executable file, owner, world-write, ACL and project restrictions. Do not change Homebrew permissions/ACLs or bypass Gatekeeper for CE; no PATH fallback. " +
26
26
  "Select an independently qualified MCP child with CE_NODE_PATH. " + hostRuntimeRepairMessage() +
27
27
  ". Installation checks are not transport, delivery, ACK or completion evidence.";
28
28
  }
29
29
  /** No raw subprocess output, paths, configuration values or exception causes. */
30
30
  export function hostRuntimeRepairMessage(nodeVersion = process.version) {
31
31
  const current = /^v\d+\.\d+\.\d+$/.test(nodeVersion) ? nodeVersion : "unrecognized";
32
- return `current Pi Node ${current}; requires approved Node ${APPROVED_RUNTIME_TUPLES.map(({ nodeVersion: version }) => version).join(" or ")} with approved SQLite; restart Pi using a trusted absolute approved Node executable. CE_NODE_PATH selects the MCP child only, not the running Pi host; each qualifies independently and need not use the same executable; mise is not required`;
32
+ return `current Pi Node ${current}; Native requires Pi Host Node >=${PI_HOST_MINIMUM_NODE_VERSION}, Node-API >=8 and a verified Native cache with SQLite >=${MINIMUM_SQLITE_VERSION} and proven capabilities. Native trust/load failure is closed, with no fallback; prepare requires separately verified pins. Explicit non-production node-sqlite retains candidate Node >=${CANDIDATE_NODE_RANGE.minimum} within majors 24/25/26 and its known-defect refusals; restart Pi using a trusted absolute approved Node executable. CE_NODE_PATH selects the MCP child only, not the running Pi host; each qualifies independently and need not use the same executable; mise is not required`;
33
33
  }
34
34
  //# sourceMappingURL=diagnostics.js.map
@@ -2,7 +2,11 @@ import { execFileSync } from "node:child_process";
2
2
  import { accessSync, constants, existsSync, lstatSync, realpathSync, statSync } from "node:fs";
3
3
  import { homedir } from "node:os";
4
4
  import { dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
5
- import { APPROVED_RUNTIME_TUPLES, REQUIRED_SQLITE_CAPABILITIES, assertRuntimeEligibility } from "../storage/runtime.js";
5
+ import { MISE_DISCOVERY_NODE_VERSIONS, probeSqliteCapabilities, assertRuntimeEligibility } from "../storage/runtime.js";
6
+ import { resolveSqliteDriver } from "../storage/sqlite-driver-selection.js";
7
+ import { createNodeSqliteDriver } from "../storage/sqlite-driver-node.js";
8
+ import { createRustNativeDriver } from "../storage/sqlite-driver-rust.js";
9
+ import { resolveWrapperIdentityEvidence } from "./wrapper-identity.js";
6
10
  /** These are locations, not PATH search. Every discovered file still needs admission. */
7
11
  const SYSTEM_DIRECTORIES = ["/usr/local/bin", "/usr/bin", "/bin", "/opt/homebrew/bin"];
8
12
  export class ExecutableRefusal extends Error {
@@ -53,7 +57,7 @@ function assertDarwinAclSafe(path) {
53
57
  }
54
58
  /** Admission is deliberately before probing. Same-account filesystem mutation is
55
59
  * outside this boundary; a private installation is required, not a signature claim. */
56
- function admitPath(path, options, kind) {
60
+ function admitPath(path, options, kind, explicitClient = false) {
57
61
  try {
58
62
  if (!isAbsolute(path) || normalize(path) !== path || /[\x00-\x1f\x7f]/.test(path))
59
63
  untrusted();
@@ -75,7 +79,11 @@ function admitPath(path, options, kind) {
75
79
  assertDarwinAclSafe(candidate);
76
80
  // OS-owned sticky temp roots protect independently owned private children.
77
81
  const stickyRoot = stat.isDirectory() && stat.uid === 0 && (stat.mode & 0o1000) !== 0;
78
- if ((stat.mode & 0o022) !== 0 && !stickyRoot)
82
+ // Explicit client selection delegates ancestor group writers to the user.
83
+ // File writes, world writes, owner and ACL checks remain strict; Node and
84
+ // Native callers never receive this client-only directory exception.
85
+ const unsafeWrites = explicitClient && stat.isDirectory() ? 0o002 : 0o022;
86
+ if ((stat.mode & unsafeWrites) !== 0 && !stickyRoot)
79
87
  untrusted();
80
88
  }
81
89
  const parent = dirname(candidate);
@@ -107,35 +115,26 @@ export function admitExecutable(path, options = {}) {
107
115
  export function admitInstallationDirectory(path, options = {}) {
108
116
  return admitPath(path, options, "directory");
109
117
  }
110
- // Inline probe imports builtins only; no project loader, package resolution,
111
- // configuration, Store, credentials, network or inherited Node options.
112
- const NODE_PROBE = `
113
- const { DatabaseSync } = require('node:sqlite');
114
- const db = new DatabaseSync(':memory:');
118
+ // Inline probe uses only the selected factory and verified Native path. No project
119
+ // loader, configuration, Store, credentials, network or inherited Node options.
120
+ function buildNodeProbe(driver) {
121
+ const factory = driver.kind === "node-sqlite"
122
+ ? `const driver = (${createNodeSqliteDriver.toString()})();`
123
+ : `const driver = (${createRustNativeDriver.toString()})(require, ${JSON.stringify(driver.nativePath)});`;
124
+ return `
125
+ ${factory}
126
+ const db = driver.open(':memory:');
115
127
  try {
116
- const row = db.prepare('SELECT sqlite_source_id() AS sourceId').get();
117
- const compileOptions = db.prepare('PRAGMA compile_options').all().map(option => {
118
- const value = Object.values(option)[0];
119
- if (typeof value !== 'string') throw new Error('invalid compile option');
120
- return value;
121
- }).sort();
122
- db.enableDefensive(true);
123
- db.exec('PRAGMA writable_schema=ON');
124
- if (db.prepare('PRAGMA writable_schema').get()?.writable_schema !== 0) throw new Error('defensive mode unavailable');
125
- db.exec('CREATE TABLE runtime_probe (value INTEGER); BEGIN');
126
- if (db.isTransaction !== true) throw new Error('transaction state unavailable');
127
- if (db.prepare('INSERT INTO runtime_probe VALUES (?)').run(1).changes !== 1
128
- || db.prepare('SELECT value FROM runtime_probe').get()?.value !== 1
129
- || db.prepare('SELECT value FROM runtime_probe').all().length !== 1) throw new Error('statement APIs unavailable');
130
- db.exec('ROLLBACK');
131
- if (db.isTransaction !== false) throw new Error('transaction state unavailable');
132
- process.stdout.write(JSON.stringify({nodeVersion:process.version,sqliteVersion:process.versions.sqlite,sqliteSourceId:row.sourceId,platform:process.platform,arch:process.arch,compileOptions,sqliteCapabilities:${JSON.stringify(REQUIRED_SQLITE_CAPABILITIES)}}));
128
+ const evidence = (${probeSqliteCapabilities.toString()})(db);
129
+ process.stdout.write(JSON.stringify({...evidence,driver:driver.kind,nodeVersion:process.version,napiVersion:process.versions.napi,sqliteVersion:driver.kind==='node-sqlite'?process.versions.sqlite:driver.nativeInfo.sqliteVersion,platform:process.platform,arch:process.arch,...(driver.nativeInfo?{native:driver.nativeInfo}:{})}));
133
130
  } finally { db.close(); }
134
131
  `;
132
+ }
135
133
  export function qualifyNodeExecutable(path, options = {}) {
136
134
  const canonical = admitExecutable(path, options);
137
135
  try {
138
- const text = execFileSync(canonical, ["--input-type=commonjs", "-e", NODE_PROBE], {
136
+ const selected = options.driver ?? resolveSqliteDriver();
137
+ const text = execFileSync(canonical, ["--input-type=commonjs", "-e", buildNodeProbe(selected)], {
139
138
  cwd: "/", env: { PATH: "/usr/bin:/bin", LANG: "C", LC_ALL: "C" },
140
139
  shell: false, timeout: 5_000, killSignal: "SIGKILL", maxBuffer: 16_384,
141
140
  encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
@@ -150,9 +149,10 @@ export function qualifyNodeExecutable(path, options = {}) {
150
149
  }
151
150
  export function resolveApprovedNode(options = {}) {
152
151
  const env = options.env ?? {};
152
+ const selected = options.driver ?? resolveSqliteDriver();
153
153
  const qualify = (path) => {
154
154
  const canonical = admitExecutable(path, options);
155
- qualifyNodeExecutable(canonical, options);
155
+ qualifyNodeExecutable(canonical, { ...options, driver: selected });
156
156
  return canonical;
157
157
  };
158
158
  if (env.CE_NODE_PATH !== undefined)
@@ -161,7 +161,7 @@ export function resolveApprovedNode(options = {}) {
161
161
  const candidates = [
162
162
  options.execPath ?? process.execPath,
163
163
  ...(options.systemDirectories ?? SYSTEM_DIRECTORIES).map((directory) => join(directory, "node")),
164
- ...(isAbsolute(legacyRoot) ? APPROVED_RUNTIME_TUPLES.map(({ nodeVersion }) => join(legacyRoot, "installs/node", nodeVersion.slice(1), "bin/node")) : []),
164
+ ...(isAbsolute(legacyRoot) ? MISE_DISCOVERY_NODE_VERSIONS.map((nodeVersion) => join(legacyRoot, "installs/node", nodeVersion.slice(1), "bin/node")) : []),
165
165
  ];
166
166
  for (const path of new Set(candidates)) {
167
167
  try {
@@ -171,6 +171,13 @@ export function resolveApprovedNode(options = {}) {
171
171
  }
172
172
  return undefined;
173
173
  }
174
+ function admitExplicitTunnelClient(path, options) {
175
+ const canonical = admitPath(path, options, "executable", true);
176
+ resolveWrapperIdentityEvidence(canonical, target => {
177
+ admitPath(target, options, "executable", true);
178
+ });
179
+ return canonical;
180
+ }
174
181
  /** Diagnostic-only closed outcome. Same runtime admission, retaining discovery
175
182
  * refusals instead of laundering rejected installations as absent. Explicit
176
183
  * overrides are authoritative: even an absent override is a refusal. */
@@ -178,7 +185,7 @@ export function diagnoseTunnelClient(options = {}) {
178
185
  const env = options.env ?? {};
179
186
  if (env.CE_TUNNEL_CLIENT_PATH !== undefined) {
180
187
  try {
181
- admitExecutable(env.CE_TUNNEL_CLIENT_PATH, options);
188
+ admitExplicitTunnelClient(env.CE_TUNNEL_CLIENT_PATH, options);
182
189
  return "TRUSTED_METADATA_ONLY";
183
190
  }
184
191
  catch {
@@ -210,7 +217,7 @@ export function diagnoseTunnelClient(options = {}) {
210
217
  export function resolveTunnelClient(options = {}) {
211
218
  const env = options.env ?? {};
212
219
  if (env.CE_TUNNEL_CLIENT_PATH !== undefined)
213
- return admitExecutable(env.CE_TUNNEL_CLIENT_PATH, options);
220
+ return admitExplicitTunnelClient(env.CE_TUNNEL_CLIENT_PATH, options);
214
221
  for (const directory of options.systemDirectories ?? SYSTEM_DIRECTORIES) {
215
222
  try {
216
223
  return admitExecutable(join(directory, "tunnel-client"), options);
@@ -0,0 +1,131 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { loadVerifiedNativeArtifact, nativeCacheRoot, nativeTarget, prepareNativeArtifact } from "../storage/native-artifact.js";
3
+ import { NATIVE_COMPAT, parseNativeCompat } from "../storage/native-compat.js";
4
+ import { readDriverSelection, writeDriverSelection } from "../storage/sqlite-driver-selection.js";
5
+ import { assertHostRuntimeEligibility } from "../storage/runtime.js";
6
+ export const NATIVE_STARTUP_WARNING = "Chat Exchange: Native Driver is not ready. Messaging is disabled. Run /ce-native to inspect or install the trusted driver.";
7
+ const reasons = {
8
+ READY: "Verified Native driver is ready.",
9
+ MISSING: "Trusted Native driver is not cached. Run /ce-native install.",
10
+ UNTRUSTED: "Native artifact or cache failed trust verification.",
11
+ INCOMPATIBLE: "Selected driver or Native identity is incompatible with CE.",
12
+ INITIALIZATION_FAILED: "Native driver initialization failed.",
13
+ UNSUPPORTED_PLATFORM: "Native driver does not support this platform or architecture.",
14
+ };
15
+ function errorCode(error) {
16
+ const code = error instanceof Error && "code" in error ? error.code : undefined;
17
+ // Never echo arbitrary loader messages, payloads, or unknown error codes.
18
+ return typeof code === "string" && /^CE_(?:NATIVE_[A-Z_]+|SQLITE_DRIVER_SELECTION_INVALID)$/.test(code)
19
+ ? code : "CE_NATIVE_INITIALIZATION_FAILED";
20
+ }
21
+ function failureState(code) {
22
+ if (code === "CE_NATIVE_CACHE_MISSING")
23
+ return "MISSING";
24
+ if (code === "CE_NATIVE_TARGET_UNSUPPORTED")
25
+ return "UNSUPPORTED_PLATFORM";
26
+ if (/HASH|UNPINNED|CACHE_UNSAFE|ASSET_INVALID|MANIFEST_INVALID/.test(code))
27
+ return "UNTRUSTED";
28
+ if (/ABI|IDENTITY|VERSION|SELECTION|DRIVER_INCOMPATIBLE/.test(code))
29
+ return "INCOMPATIBLE";
30
+ return "INITIALIZATION_FAILED";
31
+ }
32
+ /** Release asset target for a platform pair. Windows has no published Native asset. */
33
+ export function nativeTargetName(platform, arch) {
34
+ if (platform === "darwin" && arch === "arm64")
35
+ return "aarch64-apple-darwin";
36
+ if (platform === "darwin" && arch === "x64")
37
+ return "x86_64-apple-darwin";
38
+ if (platform === "linux" && arch === "x64")
39
+ return "x86_64-unknown-linux-gnu";
40
+ if (platform === "linux" && arch === "arm64")
41
+ return "aarch64-unknown-linux-gnu";
42
+ return null;
43
+ }
44
+ function supported(options) {
45
+ return ["darwin", "linux"].includes(options.platform ?? process.platform)
46
+ && ["arm64", "x64"].includes(options.arch ?? process.arch);
47
+ }
48
+ export function inspectNativeReadiness(options = {}) {
49
+ let manifest = options.manifest ?? NATIVE_COMPAT;
50
+ let driver = "rust-native";
51
+ let version = manifest.defaultVersion;
52
+ let target = null;
53
+ try {
54
+ if (!supported(options))
55
+ throw Object.assign(new Error(), { code: "CE_NATIVE_TARGET_UNSUPPORTED" });
56
+ // The loader targets this process; injected foreign platforms are diagnostic only.
57
+ const platform = options.platform ?? process.platform;
58
+ const arch = options.arch ?? process.arch;
59
+ target = nativeTargetName(platform, arch);
60
+ const selection = readDriverSelection(options.selectionFile);
61
+ driver = selection.driver;
62
+ version = selection.nativeVersion ?? manifest.defaultVersion;
63
+ if (driver !== "rust-native")
64
+ throw Object.assign(new Error(), { code: "CE_NATIVE_DRIVER_INCOMPATIBLE" });
65
+ if (selection.manifestFile !== undefined) {
66
+ try {
67
+ manifest = parseNativeCompat(JSON.parse(readFileSync(selection.manifestFile, "utf8")));
68
+ }
69
+ catch {
70
+ throw Object.assign(new Error(), { code: "CE_NATIVE_MANIFEST_INVALID" });
71
+ }
72
+ }
73
+ if (platform !== process.platform || arch !== process.arch)
74
+ throw Object.assign(new Error(), { code: "CE_NATIVE_TARGET_UNSUPPORTED" });
75
+ const verified = loadVerifiedNativeArtifact({ root: options.root ?? nativeCacheRoot(), version, manifest });
76
+ return { state: "READY", code: "CE_NATIVE_READY", reason: reasons.READY, driver, version,
77
+ abiVersion: verified.info.abiVersion, sqliteVersion: verified.info.sqliteVersion, target };
78
+ }
79
+ catch (error) {
80
+ const code = errorCode(error);
81
+ const state = failureState(code);
82
+ return { state, code, reason: reasons[state], driver, version, abiVersion: manifest.abiVersion, sqliteVersion: null, target };
83
+ }
84
+ }
85
+ /** Revalidate immediately before Tunnel side effects. Artifact presence alone is
86
+ * insufficient: the selected Native module must also pass the production Store admission battery. */
87
+ export function assertNativeReadyForTunnel() {
88
+ const readiness = inspectNativeReadiness();
89
+ if (readiness.state !== "READY")
90
+ throw Object.assign(new Error("Native is not ready; run /ce-native before starting Tunnel"), { code: readiness.code });
91
+ assertHostRuntimeEligibility();
92
+ return readiness;
93
+ }
94
+ export async function runNativeCommand(args, options = {}) {
95
+ const command = args.trim();
96
+ if (command === "" || command === "status" || command === "verify")
97
+ return JSON.stringify(inspectNativeReadiness(options), null, 2);
98
+ if (command !== "install" && command !== "repair confirm" && command !== "check-updates") {
99
+ return "Usage: /ce-native [status|install|verify|repair confirm|check-updates]. Repair requires explicit repair confirm.";
100
+ }
101
+ const manifest = options.manifest ?? NATIVE_COMPAT;
102
+ try {
103
+ if (command === "check-updates") {
104
+ // Release metadata is discovery, never an artifact trust anchor or selection input.
105
+ const response = await (options.fetchImpl ?? fetch)(`https://api.github.com/repos/${NATIVE_COMPAT.repository}/releases/latest`, {
106
+ redirect: "error", headers: { Accept: "application/vnd.github+json" }, signal: AbortSignal.timeout(10_000),
107
+ });
108
+ if (!response.ok)
109
+ throw Object.assign(new Error(), { code: "CE_NATIVE_DISCOVERY_FAILED" });
110
+ const metadata = await response.json();
111
+ if (typeof metadata !== "object" || metadata === null || !("tag_name" in metadata) || typeof metadata.tag_name !== "string") {
112
+ throw Object.assign(new Error(), { code: "CE_NATIVE_DISCOVERY_FAILED" });
113
+ }
114
+ const differs = metadata.tag_name !== `ce-sqlite-v${manifest.defaultVersion}`;
115
+ return `Current trusted Native version: ${manifest.defaultVersion}. Release discovery ${differs ? "differs; wait for a CE compatibility update" : "matches the trusted version"}. No driver was installed or selected.`;
116
+ }
117
+ if (!supported(options) || (options.platform !== undefined && options.platform !== process.platform)
118
+ || (options.arch !== undefined && options.arch !== process.arch))
119
+ throw Object.assign(new Error(), { code: "CE_NATIVE_TARGET_UNSUPPORTED" });
120
+ await prepareNativeArtifact({ root: options.root ?? nativeCacheRoot(), manifest, version: manifest.defaultVersion,
121
+ repairCorrupt: command === "repair confirm",
122
+ ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }) });
123
+ // Selection changes only after the fixed default artifact has been verified.
124
+ writeDriverSelection({ driver: "rust-native", nativeVersion: manifest.defaultVersion }, options.selectionFile);
125
+ return `Trusted Native ${manifest.defaultVersion} installed and selected. Restart Pi to initialize messaging with the installed driver.`;
126
+ }
127
+ catch (error) {
128
+ return `Native command failed (${errorCode(error)}). Current selection was not changed.`;
129
+ }
130
+ }
131
+ //# sourceMappingURL=native-readiness.js.map