@tomflow/chatloop-tools 0.4.7 → 0.4.9

package/README.md

@@ -1,27 +1,29 @@
 # @tomflow/chatloop-tools — Chat Loop 工具包
 
-**v0.4.7 · Node.js >=20 · 当前验证平台 macOS；实际发布版本以 npm Registry 为准**
+**v0.4.9 · Node.js >=20 · 当前验证平台 macOS；实际发布版本以 npm Registry 为准**
 
-本包是**本地 CLI + 统一 stdio MCP Gateway**（以下 API 合同适用于 v0.4.7，低版本以各自安装版说明为准）：一套命令管理多个工具模块的启动、停止、重启、状态；一个 MCP 入口统一对外暴露各模块的工具 API。目前代理 **Desktop Commander 0.2.44** 原有 26 个工具，新增 **Chat Loop Extension** 四个专用 Action CLI 工具（总计 30 个 MCP 工具），Repomix 尚未接入。它**不是** ChatGPT Plugin、Secure MCP Tunnel 或 Chrome 扩展；但 v0.4.6 **随 npm 自动安装一份 Chat Loop 私有的对应平台 tunnel-client 二进制依赖**，不会使用 Local Dev/Homebrew 上的程序，也不包含任何用户凭据。
+本包是**本地 CLI + 统一 stdio MCP Gateway**（以下 API 合同适用于 v0.4.9，低版本以各自安装版说明为准）：一套命令管理多个工具模块的启动、停止、重启、状态；一个 MCP 入口统一对外暴露各模块的工具 API。目前代理 **Desktop Commander 0.2.44** 原有 26 个工具，新增 **Chat Loop Extension** 四个专用 Action CLI 工具（总计 30 个 MCP 工具），Repomix 尚未接入。它**不是** ChatGPT Plugin、Secure MCP Tunnel 或 Chrome 扩展；但从 v0.4.6 起**随 npm 自动安装一份 Chat Loop 私有的对应平台 tunnel-client 二进制依赖**，不会使用 Local Dev/Homebrew 上的程序，也不包含任何用户凭据。
 
  > **给人类和 AI 的 API 合同**：此 README 随 npm 包分发，可独立阅读；对外的稳定使用入口是 `chatloop-tools` CLI（兼容别名 `chat-loop-local`）和 `chatloop-tools mcp` 提供的 MCP 协议。**无承诺的 JavaScript import/exports API**，不要依赖 `lib/` 内部模块。研发架构文档在仓库 `docs/17-local-tools-multi-tool-plan.md`，不随 npm 包发行。
 
 ## Chat Loop 专属 tunnel-client：打包内置，不依赖 Local Dev
 
-v0.4.7 延续 v0.4.6 的独立 npm 平台二进制依赖分发 OpenAI 官方 [tunnel-client v0.0.19](https://github.com/openai/tunnel-client/releases/tag/v0.0.19) 的 macOS Intel(x64)/Apple Silicon(arm64) **完整发行二进制与 cloudflared 同伴程序**分别封装在同一 `@tomflow` scope 的 `@tomflow/chatloop-tunnel-darwin-{x64,arm64}@0.0.19` 平台子包，主包用 `optionalDependencies` 由 npm **自动只安装匹配当前 OS/CPU 的包**。这仍属于 Chat Loop Tools 的内部依赖，不安装到 PATH、Homebrew 或 Local Dev。两份官方 ZIP 均按上游 SHA256SUMS 验证；将许可证、NOTICE、第三方许可证、SPDX 和二进制 SHA256 溯源一并保留。启动只调用本包自身的绝对路径，不搜索 PATH、不依赖本机 Homebrew 或 Local Dev。
+v0.4.9 延续 v0.4.6 的独立 npm 平台二进制依赖分发 OpenAI 官方 [tunnel-client v0.0.19](https://github.com/openai/tunnel-client/releases/tag/v0.0.19) 的 macOS Intel(x64)/Apple Silicon(arm64) **完整发行二进制与 cloudflared 同伴程序**分别封装在同一 `@tomflow` scope 的 `@tomflow/chatloop-tunnel-darwin-{x64,arm64}@0.0.19` 平台子包，主包用 `optionalDependencies` 由 npm **自动只安装匹配当前 OS/CPU 的包**。这仍属于 Chat Loop Tools 的内部依赖，不安装到 PATH、Homebrew 或 Local Dev。两份官方 ZIP 均按上游 SHA256SUMS 验证；将许可证、NOTICE、第三方许可证、SPDX 和二进制 SHA256 溯源一并保留。启动只调用本包自身的绝对路径，不搜索 PATH、不依赖本机 Homebrew 或 Local Dev。
 
-**版本注意**：`@latest` 始终取 npm Registry 当前最新版本；如 Registry 尚未提供 v0.4.7，下列生命周期命令只能在本仓源码或独立 v0.4.7 tarball 环境中使用。
+**版本注意**：`@latest` 始终取 npm Registry 当前最新版本；如 Registry 尚未提供 v0.4.9，下列新认证命令只能在本仓源码或独立 v0.4.9 tarball 环境中使用。
 
 ```bash
 npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools tunnel doctor
 npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools tunnel --version
-# 用户完成专属 Tunnel 的账号授权、配置后，由统一 Supervisor 启动：
+# 在 OpenAI Platform 为本用户的 Chat Loop 专属 Tunnel 创建 Restricted Runtime API key（Tunnels Read + Use）后：
+npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools tunnel auth
+# 上一命令要求真实终端，以隐藏输入方式安全保存 key，不在 argv/输出中出现；随后启动：
 npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools start tunnel
 # 兼容入口（等价于 start tunnel，不再另开未托管前台进程）：
 npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools tunnel run
 ```
 
-`tunnel doctor` 校验当前架构的 tunnel-client/cloudflared 哈希，报告 `BUNDLED_READY` 不代表连接已认证。**v0.4.7** 注册唯一组件 ID `tunnel`，由同一个 Supervisor 执行 `start|stop|restart|status tunnel`；无参命令统一涵盖已启用的 Desktop Commander 与 Tunnel。启动时只读产品自己的 `~/.chat-loop/tunnel/profiles/chat-loop.yaml`，缺少配置以 `PROFILE_NOT_FOUND` 失败而不启动。启动的真实二进制路径固定为本包对应平台依赖，唯一管理器持有子进程句柄；重复启动不复制进程，失去所有权时保留 `owner.json` 证据并安全拒绝接管、发信号。仅能停止本管理器直接持有的子进程，绝不按进程名查杀其他 Tunnel。
+`tunnel doctor` 校验当前架构的 tunnel-client/cloudflared 哈希，报告 `BUNDLED_READY` 不代表连接已认证。**v0.4.9** 注册唯一组件 ID `tunnel`，由同一个 Supervisor 执行 `start|stop|restart|status tunnel`；无参命令统一涵盖已启用的 Desktop Commander 与 Tunnel。启动时只读产品自己的 `~/.chat-loop/tunnel/profiles/chat-loop.yaml`，缺少配置以 `PROFILE_NOT_FOUND` 失败而不启动。启动的真实二进制路径固定为本包对应平台依赖，唯一管理器持有子进程句柄；重复启动不复制进程，失去所有权时保留 `owner.json` 证据并安全拒绝接管、发信号。仅能停止本管理器直接持有的子进程，绝不按进程名查杀其他 Tunnel。
 
 Supervisor 自己创建的独立 Unix 健康 Socket `<state-dir>/tools/tunnel/health.sock` 通过 `/readyz` 判断**本地启动就绪**；结果 `after=RUNNING / evidence=LOCAL_READYZ / connection=UNVERIFIED` **不代表** OpenAI 云端请求成功。最后仍必须经 ChatGPT 真实 tools/call 验证。统一 Tunnel 子进程不继承外部的 `OPENAI_ADMIN_KEY` 或 `CONTROL_PLANE_API_KEY`：若自己的 profile 使用 `env:CONTROL_PLANE_API_KEY`，用户须明确在启动该 CLI 时提供产品独立的 `CHAT_LOOP_TUNNEL_CONTROL_PLANE_API_KEY`，由适配器专门映射；也可让产品自己的 profile 指向用户自有受保护的 `file:` 密钥引用。不要把凭据放在 CLI 参数、聊天或仓库里。
 
@@ -31,7 +33,7 @@ Supervisor 自己创建的独立 Unix 健康 Socket `<state-dir>/tools/tunnel/he
 
 - **已经验证**：仓库内 CLI 生命周期、真实 Desktop Commander MCP 握手和只读调用、26 项工具发现、单工具故障隔离、Gateway 断线重连；全部在本机测试或隔离状态目录内完成。
 - **已验证（2026-11-05）**：v0.4.0 本地 tarball 在仓库外 macOS 临时目录用 npm 安装（`--ignore-scripts`），安装后的 `doctor/status/start/stop` 正常；MCP initialize、26 工具列表与 `read_file` 调用读回临时文件均通过。未改现有 Local Dev/Tunnel。
-- **已验收历史与当前缺口要区分**：旧 v0.4.3 通过用户独立 Tunnel → ChatGPT 的 26 工具发现和真实只读 tools/call；正式 npm v0.4.5 已发布、npx latest 本地 MCP 30 工具发现通过，但**当前专用 Tunnel 因安全工具阻断重连，处于 STOPPED**，v0.4.5 的远端 tools/call **仍未验收**；但真实 macOS Chrome 0.3.29 + Native Host + 本地 MCP tools/call 的 Text/DOM/PNG/Reload **已通过**，并在 Reload 后正式 Audit 复核版本/Owner 未变化。Windows/Linux、新版 MCP 2026 协议、长任务取消、最小权限及公开 Chat Loop 产品 Plugin 发布也未验收。
+- **已验收历史与当前缺口要区分**：旧 v0.4.3 通过用户独立 Tunnel → ChatGPT 的 26 工具发现和真实只读 tools/call；正式 npm v0.4.5 已发布、npx latest 本地 MCP 30 工具发现通过，这些是旧版阶段的历史记录；**当前专用 Tunnel 已通过独立 Runtime Key 和新 Chat 随机只读挑战验收**（证据以仓库 `context/CURRENT.md` 为准，本文随 npm 包分发时不代表运行中的在线状态）；真实 macOS Chrome 0.3.29 + Native Host + 本地 MCP tools/call 的 Text/DOM/PNG/Reload **已通过**，并在 Reload 后正式 Audit 复核版本/Owner 未变化。Windows/Linux、新版 MCP 2026 协议、长任务取消、最小权限及公开 Chat Loop 产品 Plugin 发布也未验收。
 - **高风险权限**：Desktop Commander 在独立 `HOME` 下运行，但仍继承**当前操作系统用户的文件、进程与命令权限**；这不是文件系统沙箱。只在获用户明确授权的机器上运行，勿以管理员权限启动，勿向不可信客户端暴露；生产级目录白名单/命令审批**尚未实现**。
 
 ## 2. 安装及入口
@@ -66,7 +68,7 @@ npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools mcp
 cd packages/local-tools
 npm pack
 # 在仓库外一个全新的目录：
-npm install /absolute/path/to/tomflow-chatloop-tools-0.4.7.tgz
+npm install /absolute/path/to/tomflow-chatloop-tools-0.4.9.tgz
 ./node_modules/.bin/chat-loop-local doctor
 ./node_modules/.bin/chat-loop-local status
 ```

package/bin/cli.mjs

@@ -9,6 +9,7 @@ import {CONTRACT,ACTIONS,registry,ensurePrivateDir,paths,
   safeFallback,recoverStaleLock,exitCode,talk} from '../lib/control.mjs';
 import {runGateway} from '../lib/gateway.mjs';
 import {tunnelDoctor,runTunnel} from '../lib/tunnel.mjs';
+import {promptTunnelRuntimeKey,storeTunnelRuntimeKey} from '../lib/tunnel-auth.mjs';
 
 const require=createRequire(import.meta.url);
 const command=process.argv[2]??'doctor';
@@ -30,7 +31,7 @@ function inspect(){
   }catch{return {status:'BLOCKED',reason:'MCP_DEPENDENCY_NOT_INSTALLED'};}
 }
 async function connectOrLaunch(request){
-  try{return await talk(request);}
+  try{return await talk(request,request.deadlineMs+2000);}
   catch(err){
     if(!['ENOENT','ECONNREFUSED','TIMEOUT','UNKNOWN_RESULT'].includes(err.code))throw err;
   }
@@ -51,7 +52,7 @@ async function connectOrLaunch(request){
   let last;
   for(let i=0;i<60;i++){
     await new Promise(resolve=>setTimeout(resolve,65));
-    try{return await talk(request);}
+    try{return await talk(request,request.deadlineMs+2000);}
     catch(err){
       last=err;
       if(err.code==='INCOMPATIBLE_VERSION')throw err;
@@ -70,7 +71,9 @@ async function runControl(action=command, params=extra){
   if(action!=='status' && !target && !registry().some(t=>t.enabled)){
     const reply=fail('NO_ENABLED_TOOLS',action,target,requestId);emit(reply);process.exitCode=5;return;
   }
-  const req={contract:CONTRACT,requestId,action,scope:target?'tool':'all',deadlineMs:12000};
+  // Real Desktop Commander cold startup can exceed 12s on loaded macOS.
+  const req={contract:CONTRACT,requestId,action,scope:target?'tool':'all',
+    deadlineMs:action==='start'||action==='restart'?25000:12000};
   if(target)req.toolId=target;
   let reply;
   try{
@@ -105,13 +108,23 @@ else if(command==='doctor'){
   }else if(extra.length===1&&extra[0]==='run'){
     // Compatibility alias: all tunnel execution now belongs to the Supervisor.
     await runControl('start',['tunnel']);
+  }else if(extra.length===1&&extra[0]==='auth'){
+    try{
+      const key=await promptTunnelRuntimeKey();
+      emit({contract:'chat-loop.local-tools.v1',command,action:'auth',
+        ...storeTunnelRuntimeKey(key)});
+    }catch(e){
+      emit({contract:'chat-loop.local-tools.v1',command,action:'auth',
+        status:'FAILED',code:e.code||'CREDENTIAL_SETUP_FAILED'});
+      process.exitCode=1;
+    }
   }else if(extra.length===1&&extra[0]==='--version'){
     try{await runTunnel(['--version']);}
     catch(e){emit({contract:'chat-loop.local-tools.v1',command,status:'FAILED',
       code:e.code||'TUNNEL_EXEC_FAILED'});process.exitCode=1;}
   }else{
     emit({contract:'chat-loop.local-tools.v1',command,status:'FAILED',
-      code:'INVALID_ARGUMENT',usage:'tunnel doctor | tunnel --version | tunnel run (managed)'});
+      code:'INVALID_ARGUMENT',usage:'tunnel doctor | tunnel --version | tunnel auth | tunnel run (managed)'});
     process.exitCode=2;
   }
 }else if(command==='capabilities'){

package/lib/adapters/tunnel.mjs

@@ -138,6 +138,7 @@ export function createTunnelAdapter({records,log},options={}){
     const rec=records.get(t.id),before=rec?.state||'STOPPED';
     if(!rec||rec.exited){
       if(isMarked())return result(t,before,'UNKNOWN','OWNERSHIP_UNCERTAIN',err('OWNERSHIP_UNCERTAIN'),null,'ORPHAN_MARKER');
+      if(rec)rec.state='STOPPED';
       return result(t,before,'STOPPED','ALREADY_STOPPED',null,null,'NO_LIVE_OWNED_CHILD');
     }
     if(ctx.remaining()<100)return result(t,before,before,'DEADLINE_EXPIRED',err('TIMEOUT'),rec.pid,'NO_SIGNAL_SENT');

package/lib/gateway.mjs

@@ -46,7 +46,7 @@ export function runGateway(){
         return reject(m.id,-32602,'UNSUPPORTED_MCP_VERSION');
       connected=true;
       return reply(m.id,{protocolVersion:m.params.protocolVersion,
-        capabilities:{tools:{}},serverInfo:{name:'chat-loop-local-tools',version:'0.4.7'}});
+        capabilities:{tools:{}},serverInfo:{name:'chat-loop-local-tools',version:'0.4.8'}});
     }
     // A modern MCP client probes discovery before falling back to legacy initialize.
     // We only implement the legacy handshake era, so report unsupported method.

package/lib/tunnel-auth.mjs

@@ -0,0 +1,64 @@
+// One-time Chat Loop runtime credential storage. Never inspect Local Dev's secrets.
+import {randomUUID} from 'node:crypto';
+import {existsSync,lstatSync,mkdirSync,readFileSync,renameSync,unlinkSync,writeFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+import {Writable} from 'node:stream';
+import {createInterface} from 'node:readline';
+
+const fail=(code)=>Object.assign(new Error(code),{code});
+function privateFile(path){
+  const stat=lstatSync(path);
+  if(!stat.isFile()||stat.isSymbolicLink()||(stat.mode&0o077)||
+    (process.getuid&&stat.uid!==process.getuid()))throw fail('INSECURE_PROFILE');
+}
+function privateDirectory(path){
+  const stat=lstatSync(path);
+  if(!stat.isDirectory()||stat.isSymbolicLink()||(stat.mode&0o077)||
+    (process.getuid&&stat.uid!==process.getuid()))throw fail('INSECURE_CREDENTIAL_DIR');
+}
+function putAtomic(path,contents){
+  const temp=path+'.'+randomUUID()+'.tmp';
+  try{
+    writeFileSync(temp,contents,{flag:'wx',mode:0o600});
+    renameSync(temp,path);
+  }finally{if(existsSync(temp))unlinkSync(temp);}
+}
+export function storeTunnelRuntimeKey(key,{root=join(homedir(),'.chat-loop','tunnel')}={}){
+  if(typeof key!=='string'||!key||key!==key.trim()||key.length>4096||
+    /[\r\n\x00-\x1f\x7f]/.test(key))throw fail('INVALID_CREDENTIAL');
+  const profile=join(root,'profiles','chat-loop.yaml');
+  try{privateFile(profile);}catch(e){
+    throw fail(e.code==='ENOENT'?'PROFILE_NOT_FOUND':e.code||'INSECURE_PROFILE');
+  }
+  const original=readFileSync(profile,'utf8');
+  const secretDir=join(root,'secrets'),secretPath=join(secretDir,'runtime-api-key');
+  const oldRef='env:CONTROL_PLANE_API_KEY',fileRef='file:'+secretPath;
+  if(original.includes(oldRef)){
+    if(original.split(oldRef).length!==2)throw fail('AMBIGUOUS_AUTH_REFERENCE');
+  }else if(!original.includes(fileRef))throw fail('FOREIGN_AUTH_REFERENCE');
+  if(!existsSync(secretDir))mkdirSync(secretDir,{recursive:true,mode:0o700});
+  privateDirectory(secretDir);
+  if(existsSync(secretPath))privateFile(secretPath);
+  const updated=original.replace(oldRef,fileRef);
+  // The secret is never written to argv, the profile or the CLI result.
+  putAtomic(secretPath,key);
+  if(updated!==original)putAtomic(profile,updated);
+  return {status:'CREDENTIAL_STORED',connection:'UNVERIFIED',profile};
+}
+export async function promptTunnelRuntimeKey(){
+  if(!process.stdin.isTTY||!process.stderr.isTTY)throw fail('INTERACTIVE_TTY_REQUIRED');
+  // readline enters raw terminal mode; its output is muted so pasted keys are not echoed.
+  const silent=new Writable({write(_chunk,_encoding,callback){callback();}});
+  const input=createInterface({input:process.stdin,output:silent,terminal:true});
+  try{
+    process.stderr.write('Paste the restricted Chat Loop runtime key (input hidden), then Enter: ');
+    return await new Promise((resolve,reject)=>{
+      input.question('',answer=>resolve(answer));
+      input.once('SIGINT',()=>reject(fail('CANCELLED')));
+    });
+  }finally{
+    input.close();
+    process.stderr.write('\n');
+  }
+}

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.7",
+  "version": "0.4.9",
   "type": "module",
   "description": "Chat Loop local tools: MCP gateway, isolated bundled tunnel-client and unified CLI",
   "bin": {