@liwu1995/afu-context 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# AFU Context
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [简体中文](README.zh-CN.md)
+
+Local asynchronous context compression for Claude Code, Codex, Pi Coding Agent and DeepSeek Harness.
+
+## Install
+
+**Release candidate; not yet published.** The npx commands below become available after the main package and platform companions are published.
+
+Requires Node.js 22.19+ (22.x) or 24+, and your host installed and logged in. Platform-pack builds prepare a private Python runtime on supported Mac/Linux systems. Legacy/source and Windows builds still require Python 3.11+. Platform packs must be published and verified before advertising the one-command flow as generally available.
+
+```sh
+npx @liwu1995/afu-context install  # detects installed hosts; asks when multiple are found
+# Non-interactive: npx @liwu1995/afu-context install claude
+```
+
+CC/Codex install no Pi/DSH JavaScript dependencies. Selecting Pi or DSH downloads only that platform’s pinned dependencies into a private versioned cache.
+
+The first command prepares AFU's CLI. First use creates a private Python environment and installs pinned dependencies, reusing uv when available or using pip. Set `AFU_PYTHON` to select your Python executable. No system Python modifications or separate summary API key are needed.
+
+| Host | Integration | Launch | Validated compatibility |
+| --- | --- | --- | --- |
+| Claude Code | Local gateway and startup hooks | `claude` | macOS/Linux sandbox; Windows implementation awaits machine validation |
+| Codex CLI | Local gateway and startup hooks | `codex` | macOS/Linux; not a desktop App plugin; Windows native integration disabled |
+| Pi | Launcher-loaded extension | `afu pi -- --provider PROVIDER --model MODEL` | Pi 0.84.4, macOS/Linux |
+| DSH | Temporary profile overlay | `afu dsh -- --profile PROFILE` | DSH 0.1.2-rc.1 / Cordis 4.0.2, macOS/Linux |
+
+Native services use user launchd on macOS, systemd user services on Linux, and the existing Windows scheduled-task integration for Claude Code. Linux native automatic installation requires a working `systemctl --user`. Codex may require approving its hooks. Host credentials remain owned by the host. Official Claude subscription/OAuth and Windows real-machine acceptance remain pending.
+
+## Diagnostics
+
+```sh
+afu status
+afu status claude --json
+afu ui --open
+```
+
+The local read-only dashboard distinguishes installation, observed requests, summary generation and confirmed application. It includes disk/running versions, sessions, timelines, receipts, cache usage and fixed error reasons. Pi/DSH application indicates successful host-history commit; CC/Codex application requires a complete successful upstream response with the replacement. Historical runtime events do not assert that a process is currently alive.
+
+Only allowlisted metadata is logged. Prompts, summary text, credentials, raw provider errors and conversation files are not exposed in the panel. It binds to loopback and requires a random access capability; do not share the printed URL. Cache counters absent from a provider are unknown, not zero. Pi/DSH chat usage and cost analysis are not provided in this version.
+
+## Remove
+
+```sh
+afu remove claude  # substitute codex, pi or dsh
+```
+
+Only settings still owned by AFU are restored. Later user changes and existing sessions are preserved. Native clients still using an old route retain passthrough; Pi/DSH future wrapper launches bypass AFU. Remove the integration before uninstalling the npm package. Versioned runtime caches and diagnostic logs remain available for active sessions and inspection.
+
+## Configuration
+
+- `AFU_PYTHON`: Python 3.11+ executable.
+- `AFU_RUNTIME_DIR`: isolated Python runtime cache.
+- `AFU_STATE_DIR`: integration receipts and metadata logs.
+- `afu install claude --context-window 200000`: explicit CC window; substitute Codex where appropriate. A changed build or explicit configuration creates a healthy new generation before switching future sessions; existing sessions keep their original endpoint.
+- Pi/DSH follow the selected model's declared window. Default trigger ratio: 40% at 1M or above, 50% otherwise. Host metadata unavailable means AFU yields to native behavior.
+- `--config-dir` and `--no-autostart` support disposable native sandbox tests; do not substitute hooks-only tests for production service-manager acceptance.
+
+This package includes generic context-management code, host adapters, local diagnostics and a public Qwen tokenizer resource with its attribution. It includes no hosted monitoring service or business-specific backend.
+
+Licensed under Apache-2.0. Third-party dependencies retain their respective licenses.
+
+## Upgrade and model windows
+
+Run `afu upgrade claude` (or `codex`) after updating the package. New sessions use the new generation; restart is not forced on existing sessions. Old generation directories are retained for those sessions.
+
+CC/Codex default to querying the selected model’s provider metadata after a completed request. The lookup is off the chat response path. Default trigger: 40% for windows >= 1M, otherwise 50%. If the provider does not declare a window, new compression is skipped and status reports `manual_window_required`; normal chat continues. Use `afu install claude --context-window 200000` with the actual known capacity to override. An explicit window remains explicit after a model switch until you reconfigure it. OpenAI-compatible model catalogs are not guaranteed to expose context limits.
+
+### Recovery and cache maintenance
+
+Interrupted native upgrades are journaled. The next install/upgrade/remove or native startup completes the switch, or restores the previous configuration if the candidate cannot start. Concurrent user edits stop recovery rather than being overwritten.
+
+Use `afu gc --dry-run` to preview reclamation and `afu gc` to perform it. Current, busy, pending and unrecognized legacy generations are retained. Retired native services require released client leases and five idle minutes before retirement. Unreferenced managed caches require 24 hours of age; active installers and other registered AFU state directories protect their caches.
+
+Use `afu install claude --context-window auto --ratio auto` (or `codex`) to reset manual overrides. Omitted options preserve existing settings. Unknown model capacity pauses new compression; chat continues.
+
+Host dependencies use release lockfiles and `npm ci` with integrity checks. Pi also ships its upstream shrinkwrap. Installation subprocesses have a 180-second deadline; `AFU_INSTALL_TIMEOUT_MS` may set 1–600000 milliseconds. A timeout stops only that installer's process group and leaves existing generations intact. Registry or integrity errors remain failures; integrity validation is never disabled.
+
+Pi/DSH also persist `afu install pi --context-window 200000 --ratio 0.2` (substitute `dsh`). Launcher options take precedence over environment variables, then saved settings, then automatic model defaults. Explicit `auto` resets the override. Invalid ratios/windows fail without changing saved settings. After removal, `afu pi -- <host arguments>` and `afu dsh -- <host arguments>` launch the host without preparing AFU runtimes or downloading dependencies.
+
+Upgrade recovery is scoped to the selected host/configuration directory. Management failures report an allowlisted reason code, phase, recovery hint, and a bounded latest-error record under the chosen state directory's `logs/management-error.json`. Raw exception text, credentials and host settings are not included.
+
+## Platform-pack release (candidate; not published)
+
+Build the main package with `scripts/build_distribution.py --prebuilt`. Build each runtime/Pi/DSH companion on its target system using `scripts/build_platform_pack.py`. Runtime sources must be relocatable standalone Python; host-pack sources must be lockfile-verified platform caches. Publish companions before the main package, then test the registry installation from a clean user account. Never label local-pack tests as registry publication verification.
+
+`AFU_BUNDLE_DIR` selects a local directory of companion packages for offline installs and sandbox validation. Each companion must match the main build, OS and architecture; all payload files are hashed and escaping links or extra files are rejected. CC/Codex do not fetch Pi/DSH companions. `install --dry-run` checks host availability, writable state and the user service manager without installing runtimes or editing host settings.
+
+After a temporary npx install, use `npx @liwu1995/afu-context status` and `npx @liwu1995/afu-context pi -- ...` / `npx @liwu1995/afu-context dsh -- ...`; native CC/Codex retain their normal launch commands. Successful installation is not proof of request routing or summary application.
+
+### Linux without a systemd user session
+
+If installation reports `USER_SERVICE_UNAVAILABLE`, host settings have not been
+changed. Enable your systemd user service, or explicitly choose manual startup:
+
+```sh
+afu install codex --no-autostart
+# For Claude Code: afu install claude --no-autostart
+```
+
+Keep the same `--config-dir`, `--state`, upstream and other options if you used
+custom settings. Manual mode starts the gateway now but does not register login
+or reboot recovery. Before using the host after reboot, rerun the same install
+command with `--no-autostart`. Do not expect the gateway to restart automatically.
+
+Linux `status` displays `startup.mode` separately from `healthy`. A matching
+service file and registration receipt produce `registration_recorded`; this is
+not a live systemd enablement check or proof that a reboot has been tested. Missing
+or edited service files are reported as `registration_file_changed_or_missing`.

package/README.zh-CN.md

@@ -0,0 +1,79 @@
+# AFU Context
+
+[English](README.md) · **简体中文**
+
+为 Claude Code、Codex、Pi Coding Agent 和 DeepSeek Harness 提供本地异步上下文压缩与诊断。后台准备摘要，覆盖范围仍然匹配时再应用。
+
+## 安装
+
+**当前为未发布的候选包。** 以下 npx 命令在主包和对应平台配套包正式发布后可用：
+
+```sh
+npx @liwu1995/afu-context install
+# 非交互安装：npx @liwu1995/afu-context install claude
+```
+
+需要 Node.js 22.19+（22.x）或 24+，以及已安装并登录的宿主。支持的平台配套包在 Mac/Linux 准备私有 Python 运行时；源码、旧分发和 Windows 路径仍需要 Python 3.11+。不修改系统 Python，不需要单独配置摘要模型密钥。`AFU_PYTHON` 可指定解释器。
+
+| 框架 | 接入方式 | 启动 | 验证范围 |
+| --- | --- | --- | --- |
+| Claude Code | 本地网关与启动 Hook | `claude` | Mac/Linux 沙箱；Windows 待实机验收 |
+| Codex CLI | 本地网关与启动 Hook | `codex` | Mac/Linux；不是桌面 App 插件；Windows 原生接入未启用 |
+| Pi | 启动时加载扩展 | `afu pi -- --provider PROVIDER --model MODEL` | Pi 0.84.4，Mac/Linux |
+| DSH | 临时 profile 覆盖 | `afu dsh -- --profile PROFILE` | DSH 0.1.2-rc.1 / Cordis 4.0.2，Mac/Linux |
+
+CC/Codex 不下载 Pi/DSH 依赖；选择 Pi 或 DSH 时才准备对应的锁定版本依赖。临时 npx 安装后使用 `npx @liwu1995/afu-context status` 和 `npx @liwu1995/afu-context pi -- ...` / `npx @liwu1995/afu-context dsh -- ...`；原生 CC/Codex 继续照常启动。
+
+macOS 使用用户级 launchd，Linux 使用 systemd 用户服务，Windows Claude Code 使用计划任务。Codex 可能需要确认启用 Hook。宿主继续管理认证；官方 Claude 订阅/OAuth 和 Windows 实机验收尚未完成。
+
+## 状态与面板
+
+```sh
+afu status
+afu status claude --json
+afu ui --open
+```
+
+只读面板分别展示已安装、请求已观测、摘要就绪、应用已确认，以及磁盘/运行版本、时间线、缓存 usage 和错误原因。Pi/DSH 应用回执表示宿主历史提交；CC/Codex 还需包含替换的上游请求完整成功。历史事件不代表进程仍存活。
+
+仅记录允许的元数据，不展示对话正文、摘要正文、认证、原始模型错误或会话文件。面板只监听回环地址并要求随机访问凭证，不要分享启动时的链接。未返回缓存指标时显示未知，不当作零。当前不提供 Pi/DSH 主请求 usage 或成本分析。
+
+## 移除与升级
+
+```sh
+afu remove claude   # 可换为 codex、pi、dsh
+afu upgrade claude  # 更新 npm 包后执行；也支持 codex
+```
+
+仅恢复仍由 AFU 拥有的配置；保留用户后续修改和已有会话。旧原生会话保留透传，Pi/DSH 后续启动绕过 AFU。卸载 npm 包前先移除接入。旧运行时目录、缓存和诊断日志保留供已有会话使用与检查。
+
+升级先验证新服务健康，再切换新会话，不强制重启已有会话。恢复操作限定在指定宿主及配置目录。管理错误以允许的原因码、阶段和恢复提示写入状态目录的 `logs/management-error.json`，不写入原始异常或认证信息。
+
+## 配置与模型窗口
+
+- `AFU_RUNTIME_DIR`：版本化运行时缓存；`AFU_STATE_DIR`：接入回执与日志。
+- CC/Codex 在主请求结束后异步查询当前模型的供应商元数据；默认窗口 ≥1M 时 40%，其它窗口 50%。未知窗口暂停新压缩，聊天继续。
+- `afu install claude --context-window 200000 --ratio 0.2` 可显式覆盖；`--context-window auto --ratio auto` 恢复自动配置。省略选项保留已有设置，非法值不修改配置。
+- Pi/DSH 跟随宿主当前模型、认证和声明窗口。窗口缺失时保留原生行为。支持 `afu install pi --context-window 200000 --ratio 0.2`，也可换为 dsh；优先级为启动选项、环境变量、保存的配置、自动默认值。阈值使用可压缩工作集的 token 估算，不等同状态栏总用量。
+- `--config-dir`、`--state`、`--no-autostart` 用于独立沙箱或手动管理。不要将 Hook 测试当作系统服务恢复验收。
+
+依赖使用发行锁文件、`npm ci` 与完整性检查；Pi 还包含上游 shrinkwrap。安装子进程默认超时 180 秒，`AFU_INSTALL_TIMEOUT_MS` 可设为 1–600000 毫秒。超时只停止本次安装进程组，不改变已有运行版本；不会关闭完整性校验来绕过下载错误。
+
+## 平台配套包
+
+维护者使用 `scripts/build_distribution.py --prebuilt` 构建主包，在目标系统用 `scripts/build_platform_pack.py` 构建 runtime/Pi/DSH 配套包。Python 来源须可迁移，宿主依赖须匹配锁文件。配套包先发布，主包最后发布，再从全新用户环境验证公网安装。
+
+`AFU_BUNDLE_DIR` 可指向本地配套包目录，供离线安装和沙箱验证。配套包须与主包构建、系统、架构一致；逐文件校验，拒绝越界链接或多余文件。`install --dry-run` 只检查宿主、状态目录和服务管理器，不安装运行时、不修改宿主配置。本地归档验收不等于公网发布验收。
+
+### Linux 没有 systemd 用户会话时
+
+若安装返回 `USER_SERVICE_UNAVAILABLE`，宿主配置尚未改变。启用 systemd 用户服务，或明确选择手动启动：
+
+```sh
+afu install codex --no-autostart
+# Claude Code：afu install claude --no-autostart
+```
+
+保留原来的配置目录、状态目录、上游等参数。手动模式启动当前网关，但不注册登录/重启恢复；重启后需再次执行同一安装命令。`status` 分别显示启动模式与健康状态；`registration_recorded` 表示注册文件和回执匹配，不等于实时 systemd 状态或整机重启已验收。
+
+本包包含通用上下文管理、宿主适配器、本地诊断及带来源声明的公共 Qwen tokenizer，不依赖托管监控或业务后端。项目使用 Apache-2.0，第三方依赖保留各自许可证。

package/bin/afu.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/** No postinstall side effects; recover only our versioned runtime cache. */
+import {spawn} from 'node:child_process';
+import {readFileSync} from 'node:fs';
+import {dirname,join,resolve} from 'node:path';
+import {homedir} from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {guide} from './install-guide.mjs';
+import {prepareRuntime} from './runtime.mjs';
+import {holdCache} from './cache-lease.mjs';
+import {preparePlatform} from './platform.mjs';
+const root=resolve(dirname(fileURLToPath(import.meta.url)),'..');
+const manifest=JSON.parse(readFileSync(join(root,'release.json'),'utf8'));
+const env={...process.env,AFU_INSTALL_ROOT:root};
+let args=process.argv.slice(2);
+if(['install','upgrade','status','remove','gc','native'].includes(args[0])){
+ const at=args.indexOf('--state');if(at>=0&&args[at+1])env.AFU_STATE_DIR=resolve(args[at+1]);
+}
+let release;
+try{
+  if(!args.length || (args.includes('--help') && (args.indexOf('--')<0 || args.indexOf('--help')<args.indexOf('--')))){
+    console.log('AFU Context: install [claude|codex|pi|dsh], status, remove HOST, gc --dry-run, ui.\nRun npx @liwu1995/afu-context install to detect your installed host. Host login remains managed by the host.');
+    process.exit(0);
+  }
+  args=await guide(args,env);
+  if(['install','upgrade'].includes(args[0])&&args.includes('--dry-run')){
+    console.log(JSON.stringify({preflight:'passed',host:args[1],configuration_changed:false,request_observed:false}));process.exit(0);
+  }
+  let removed=false;
+  if(['pi','dsh'].includes(args[0])){
+    const receipt=join(env.AFU_STATE_DIR??join(homedir(),'.local/share/afu-context'),'integrations',args[0]+'.json');
+    try{removed=JSON.parse(readFileSync(receipt,'utf8')).removed===true;}catch(e){if(e.code!=='ENOENT')throw Error('INVALID_INSTALLATION_RECORD');}
+  }
+  if(removed){
+    const split=args.indexOf('--');
+    if(split<0 && args.length>1)throw Error('PLUGIN_REMOVED: pass host arguments after --');
+    // COSEC: fixed host executable, argv array, no shell; no runtime downloads.
+    const child=spawn(args[0],split<0?[]:args.slice(split+1),{stdio:'inherit',env,shell:false});
+    for(const signal of ['SIGINT','SIGTERM'])process.on(signal,()=>child.kill(signal));
+    child.on('error',()=>{console.error('AFU: HOST_EXECUTABLE_UNAVAILABLE');process.exitCode=1;});
+    child.on('exit',(code,signal)=>{process.exitCode=code??(signal?130:1);});
+  }else{
+  release=await holdCache(manifest.build,env);
+  const location=await prepareRuntime(root,manifest,env);
+  const python=join(location,process.platform==='win32'?'Scripts/python.exe':'bin/python');
+  env.AFU_INSTALL_ROOT=await preparePlatform(root,manifest,args,env);
+  const child=spawn(python,['-m','afu_context.local_cli',...args],{stdio:'inherit',env});
+  // Relay signals only to our own foreground child; never enumerate other sessions.
+  for(const signal of ['SIGINT','SIGTERM'])process.on(signal,()=>child.kill(signal));
+  child.on('error',()=>{release?.();console.error('AFU failed to start');process.exitCode=1;});
+  child.on('exit',(code,signal)=>{release?.();if(code===0&&['install','upgrade'].includes(args[0]))console.error(`AFU: installed ${args[1]}; ${['claude','codex'].includes(args[1])?'service checked; open a new '+args[1]+' session':'launch with afu '+args[1]}. Waiting for the first observed request; compression is not yet verified.`);process.exitCode=code ?? (signal?130:1);});
+  }
+}catch(error){release?.();console.error('AFU: '+error.message);process.exitCode=1;}

package/bin/cache-lease.mjs

@@ -0,0 +1,16 @@
+import {mkdirSync,writeFileSync,rmSync} from 'node:fs';
+import {join} from 'node:path';
+import {homedir} from 'node:os';
+import {randomUUID,createHash} from 'node:crypto';
+import {recoverLock} from './runtime.mjs';
+export async function holdCache(build,env=process.env){
+ if(!/^[a-f0-9]{64}$/.test(build))throw Error('Invalid build identity');
+ const base=env.AFU_RUNTIME_DIR??join(homedir(),'.local/share/afu-context/runtimes');
+ mkdirSync(base,{recursive:true,mode:0o700});
+ const guard=join(base,'.gc-lock');const end=Date.now()+10000;
+ while(true){try{mkdirSync(guard);writeFileSync(join(guard,'owner.json'),JSON.stringify({pid:process.pid}));break;}catch(e){if(e.code!=='EEXIST')throw e;recoverLock(guard);if(Date.now()>end)throw Error('CACHE_GC_BUSY');await new Promise(r=>setTimeout(r,50));}}
+ const file=join(base,'.clients',randomUUID()+'.json');
+ const state=env.AFU_STATE_DIR??join(homedir(),'.local/share/afu-context');
+ try{mkdirSync(join(base,'.owners'),{recursive:true,mode:0o700});writeFileSync(join(base,'.owners',createHash('sha256').update(state).digest('hex')+'.json'),JSON.stringify({state}),{mode:0o600});mkdirSync(join(base,'.clients'),{recursive:true,mode:0o700});writeFileSync(file,JSON.stringify({pid:process.pid,build}),{mode:0o600});}finally{rmSync(guard,{recursive:true,force:true});}
+ const release=()=>rmSync(file,{force:true});process.once('exit',release);return release;
+}

package/bin/install-guide.mjs

@@ -0,0 +1,34 @@
+import {spawnSync} from 'node:child_process';
+import {accessSync,statSync,constants,mkdirSync,rmSync,mkdtempSync} from 'node:fs';
+import {join,delimiter,resolve} from 'node:path';
+import {homedir} from 'node:os';
+import {createInterface} from 'node:readline/promises';
+export function hostAvailable(host,env=process.env){
+ return (env.PATH??env.Path??'').split(delimiter).some(dir=>['',...(process.platform==='win32'?['.exe','.cmd']:[])].some(ext=>{try{accessSync(join(dir,host+ext),constants.X_OK);return statSync(join(dir,host+ext)).isFile();}catch{return false;}}));
+}
+export async function guide(args,env=process.env){
+ if(args[0]!=='install'&&args[0]!=='upgrade')return args;
+ const hosts=['claude','codex','pi','dsh'];let host=hosts.includes(args[1])?args[1]:null;
+ if(!host){
+  const available=hosts.filter(h=>hostAvailable(h,env));
+  if(!available.length)throw Error('HOST_NOT_FOUND: install and sign into your host first');
+  if(available.length===1)host=available[0];
+  else{
+   if(!process.stdin.isTTY)throw Error('HOST_SELECTION_REQUIRED: use install '+available.join('|'));
+   const input=createInterface({input:process.stdin,output:process.stderr});
+   try{console.error(available.map((h,i)=>`${i+1}. ${h}`).join('\n'));host=available[Number(await input.question('Select host: '))-1];}finally{input.close();}
+   if(!host)throw Error('INVALID_HOST_SELECTION');
+  }
+  args=[args[0],host,...args.slice(1)];
+ }
+ if(!hostAvailable(host,env))throw Error('HOST_NOT_FOUND: '+host);
+ if(process.platform==='win32'&&host==='codex')throw Error('WINDOWS_CODEX_NATIVE_UNSUPPORTED');
+ const at=args.indexOf('--state');const state=at>=0?resolve(args[at+1]):env.AFU_STATE_DIR??join(homedir(),'.local/share/afu-context');
+ mkdirSync(state,{recursive:true,mode:0o700});const check=mkdtempSync(join(state,'.write-check-'));rmSync(check,{recursive:true});
+ if(['claude','codex'].includes(host)&&!args.includes('--no-autostart')){
+  const probe=process.platform==='linux'?['systemctl',['--user','show-environment']]:process.platform==='darwin'?['launchctl',['print',`gui/${process.getuid()}`]]:null;
+  if(probe&&spawnSync(probe[0],probe[1],{env,stdio:'ignore',timeout:5000}).status!==0)throw Error(process.platform==='linux' ? `USER_SERVICE_UNAVAILABLE: no host settings changed. Enable your systemd user service, or rerun the same command with --no-autostart (example: afu ${args[0]} ${host} --no-autostart). Keep your existing --config-dir/--state and other options. Manual mode starts the gateway now but does not register login/reboot recovery; rerun it after reboot before using the host.` : 'USER_SERVICE_UNAVAILABLE: no host settings changed; enable your user service manager first');
+ }
+ console.error(`AFU: preflight passed for ${host}; preparing private runtime`);
+ return args;
+}

package/bin/install-process.mjs

@@ -0,0 +1,19 @@
+/** Bounded child lifetime, restricted to the process group created by this call. */
+import {spawn} from 'node:child_process';
+export function runInstall(command,args,env=process.env,onChild=()=>{}){
+ const ms=Number(env.AFU_INSTALL_TIMEOUT_MS??180000);
+ if(!Number.isFinite(ms)||ms<1||ms>600000)throw Error('INVALID_INSTALL_TIMEOUT');
+ return new Promise((resolve,reject)=>{
+  const child=spawn(command,args,{env,stdio:['inherit',2,2],shell:false,detached:process.platform!=='win32'});
+  let reason=null,killTimer;
+  const signal=s=>{if(!child.pid||child.exitCode!==null)return;try{process.platform==='win32'?child.kill(s):process.kill(-child.pid,s);}catch(e){if(e.code!=='ESRCH')throw e;}};
+  const cancel=code=>{if(reason)return;reason=code;signal('SIGTERM');killTimer=setTimeout(()=>signal('SIGKILL'),2000);};
+  const interrupted=()=>cancel('INSTALL_INTERRUPTED');
+  const timer=setTimeout(()=>cancel('INSTALL_TIMEOUT'),ms);
+  process.on('SIGINT',interrupted);process.on('SIGTERM',interrupted);
+  const cleanup=()=>{clearTimeout(timer);clearTimeout(killTimer);process.off('SIGINT',interrupted);process.off('SIGTERM',interrupted);};
+  child.once('error',()=>{cleanup();reject(Error('INSTALL_EXECUTABLE_UNAVAILABLE'));});
+  child.once('exit',code=>{cleanup();code===0&&!reason?resolve():reject(Error(reason??'INSTALL_FAILED_CHECK_DOWNLOAD_LOG'));});
+  try{if(child.pid)onChild(child.pid);}catch{cancel('INSTALL_OWNERSHIP_LOST');}
+ });
+}

package/bin/platform.mjs

@@ -0,0 +1,69 @@
+import {obtainPack} from './prebuilt.mjs';
+import {runInstall} from './install-process.mjs';
+/** Host-only dependencies live outside the installed npm package. */
+import {mkdirSync,readFileSync,writeFileSync,existsSync,rmSync,cpSync,renameSync} from 'node:fs';
+import {join,dirname,delimiter} from 'node:path';
+import {homedir} from 'node:os';
+
+import {spawnSync} from 'node:child_process';
+import {pathToFileURL} from 'node:url';
+import {randomUUID} from 'node:crypto';
+import {recoverLock} from './runtime.mjs';
+const read=p=>{try{return JSON.parse(readFileSync(p,'utf8'));}catch{return null;}};
+export function npmInvocation(env=process.env,platform=process.platform){
+  if(platform!=='win32')return ['npm',[]];
+  const candidates=[join(dirname(process.execPath),'node_modules/npm/bin/npm-cli.js'),
+    ...String(env.PATH??env.Path??'').split(delimiter).map(p=>join(p,'node_modules/npm/bin/npm-cli.js'))];
+  const cli=candidates.find(p=>existsSync(p));
+  if(!cli)throw Error('Cannot locate npm-cli.js; install Node.js with npm');
+  return [process.execPath,[cli]];
+}
+export async function preparePlatform(root,manifest,args,env=process.env){
+  const host=['install','upgrade'].includes(args[0])?args[1]:args[0];
+  if(!['pi','dsh'].includes(host))return root;
+  const dependencies=read(join(root,'platform-dependencies.json'))?.[host];
+  if(!dependencies)throw Error('Missing platform dependency manifest');
+  const base=env.AFU_RUNTIME_DIR??join(homedir(),'.local/share/afu-context/runtimes');
+  const canonical=join(base,manifest.build+'-'+host),pointer=canonical+'.location.json',lock=canonical+'.lock',token=randomUUID();
+  let target=canonical;
+  const refresh=()=>{const name=read(pointer)?.name;target=typeof name==='string'&&name.startsWith(manifest.build+'-'+host)&&!/[\\/]/.test(name)?join(base,name):canonical;};
+  refresh();
+  const ready=()=>read(join(target,'platform-ready.json'))?.build===manifest.build && Object.keys(dependencies).every(name=>existsSync(join(target,'node_modules',name,'package.json'))) && spawnSync(process.execPath,['--input-type=module','-e','await import(process.argv[1])',pathToFileURL(join(target,'src/afu_host_integrations',host,'dist/index.js')).href],{env,stdio:'ignore',timeout:10000}).status===0;
+  mkdirSync(base,{recursive:true,mode:0o700});
+  const deadline=Date.now()+180000;
+  while(true){
+    refresh();if(ready())return target;
+    try{mkdirSync(lock);writeFileSync(join(lock,'owner.json'),JSON.stringify({pid:process.pid,token}));break;}
+    catch(e){if(e.code!=='EEXIST')throw e;}
+    recoverLock(lock);if(Date.now()>deadline)throw Error('Platform installation still pending');
+    await new Promise(r=>setTimeout(r,300));
+  }
+  const owns=()=>read(join(lock,'owner.json'))?.token===token;
+  if(!owns())return target;
+  let createdTarget;
+  try{
+    refresh();if(ready())return target;
+    // Never repair in place: an older host may still import files from this tree.
+    target=canonical+'-generation-'+randomUUID();
+    createdTarget=target;
+    mkdirSync(target,{recursive:true,mode:0o700});
+    for(const name of ['src/afu_host_integrations','scripts'])cpSync(join(root,name),join(target,name),{recursive:true});
+    cpSync(join(root,'release.json'),join(target,'release.json'));
+    cpSync(join(root,'platform-locks',host,'package.json'),join(target,'package.json'));
+    cpSync(join(root,'platform-locks',host,'package-lock.json'),join(target,'package-lock.json'));
+    // COSEC: fixed package names/versions from the release, no shell interpolation.
+    const [executable,prefix]=npmInvocation(env);
+    if(manifest.prebuilt && process.platform!=='win32'){
+      const payload=await obtainPack(root,manifest,host,env,pid=>writeFileSync(join(lock,'owner.json'),JSON.stringify({pid:process.pid,childPid:pid,token}),{mode:0o600}));
+      cpSync(join(payload,'node_modules'),join(target,'node_modules'),{recursive:true,verbatimSymlinks:true});
+    }else await runInstall(executable,[...prefix,'ci','--registry=https://registry.npmjs.org','--prefix',target,'--ignore-scripts','--no-audit','--no-fund'],env,pid=>writeFileSync(join(lock,'owner.json'),JSON.stringify({pid:process.pid,childPid:pid,token})));
+    // Import the real adapters: a package.json marker alone misses broken files
+    // and corrupt transitive dependencies. No model request is made by imports.
+    await runInstall(process.execPath,['--input-type=module','-e','await import(process.argv[1])',pathToFileURL(join(target,'src/afu_host_integrations',host,'dist/index.js')).href],env);
+    writeFileSync(join(target,'platform-ready.json'),JSON.stringify({build:manifest.build,cache_protocol:1}),{mode:0o600});
+    const temp=pointer+'.'+token;writeFileSync(temp,JSON.stringify({name:target.slice(base.length+1)}),{mode:0o600});renameSync(temp,pointer);return target;
+  }catch(error){
+    if(owns()&&createdTarget)rmSync(createdTarget,{recursive:true,force:true});
+    throw error;
+  }finally{if(owns())rmSync(lock,{recursive:true,force:true});}
+}