@tomflow/chatloop-tools 0.4.3 → 0.4.5

package/README.md

@@ -1,8 +1,8 @@
 # @tomflow/chatloop-tools — Chat Loop 工具包
 
-**v0.4.3 · npm 安装包 · Node.js >=20 · 当前验证平台 macOS**
+**v0.4.5 · npm 安装包 · Node.js >=20 · 当前验证平台 macOS**
 
-本包是**本地 CLI + 统一 stdio MCP Gateway**：一套命令管理多个工具模块的启动、停止、重启、状态；一个 MCP 入口统一对外暴露各模块的工具 API。目前正式启用 **Desktop Commander 0.2.44**（26 个工具）；Repomix 尚未接入。它**不是** ChatGPT Plugin、Secure MCP Tunnel、tunnel-client 或 Chrome 扩展，也不会替用户安装这些组件。
+本包是**本地 CLI + 统一 stdio MCP Gateway**：一套命令管理多个工具模块的启动、停止、重启、状态；一个 MCP 入口统一对外暴露各模块的工具 API。目前代理 **Desktop Commander 0.2.44** 原有 26 个工具，新增 **Chat Loop Extension** 四个专用 Action CLI 工具（总计 30 个 MCP 工具），Repomix 尚未接入。它**不是** ChatGPT Plugin、Secure MCP Tunnel、tunnel-client 或 Chrome 扩展，也不会替用户安装这些组件。
 
  > **给人类和 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 包发行。
 
@@ -30,13 +30,22 @@ node packages/local-tools/bin/cli.mjs stop desktop-commander
 
 ### 独立 tarball：macOS 临时目录已通过实际验收
 
-**正式 npm 安装**：在包发布到 npm registry 后，运行 `npm install -g @tomflow/chatloop-tools@0.4.3`，随后执行 `chatloop-tools doctor`、`chatloop-tools status`、`chatloop-tools start desktop-commander`。也可在本地生成 tarball（不发布）：
+**推荐 CLI 入口：npx 默认 latest**。不需要在命令行预先指定安装位置，默认使用 npm 当前可解析的正式最新版；npm 负责缓存及按其默认规则重新验证元数据，有可用缓存通常复用，无缓存或需更新时允许安装：
+```bash
+npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools doctor
+npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools status
+npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools start desktop-commander
+npx --yes --package=@tomflow/chatloop-tools@latest chatloop-tools mcp
+```
+`--yes` 只跳过 npm 的安装确认，不会强制每次联网；**不使用** `--no-install`、`--offline`、`--prefer-online` 或 `--prefer-offline`。npm 默认缓存元数据有有效期，不能承诺每次立刻发现刚发布的新版本；`@latest` 保证按 npm 对 latest 的解析规则选取版本，并不自动升级运行中 Supervisor/Chrome 扩展。已运行旧版本与新 CLI 不兼容时安全拒绝，不擅自杀旧进程。稳定部署/可追溯回滚可以选择显式固定版本，默认日常命令用 latest。
+
+也支持正式 npm 安装（如 `npm install -g @tomflow/chatloop-tools@latest`），以及本地生成 tarball（不发布）：
 
 ```bash
 cd packages/local-tools
 npm pack
 # 在仓库外一个全新的目录：
-npm install /absolute/path/to/tomflow-chatloop-tools-0.4.3.tgz
+npm install /absolute/path/to/tomflow-chatloop-tools-0.4.5.tgz
 ./node_modules/.bin/chat-loop-local doctor
 ./node_modules/.bin/chat-loop-local status
 ```
@@ -128,7 +137,20 @@ npm install /absolute/path/to/tomflow-chatloop-tools-0.4.3.tgz
 
 **异常处理**：JSON-RPC 协议失败时使用顶层 `error`；工具调用失败时可能是 `result:{"isError":true,"content":[{"type":"text","text":"TOOL_UNAVAILABLE"}]}`。**必须同时检查 `error` 和 `result.isError`**。未知名字 `UNKNOWN_TOOL`，非对象 `arguments` 为 `INVALID_ARGUMENT`，未初始化为 `NOT_INITIALIZED`。真实工具可能返回自身业务错误，不都由 Gateway 转换。
 
-**限制**：Gateway 单次工具调用预算约 12 秒、Desktop Commander Adapter 约 9 秒；超时**不保证取消实际副作用**。不能自动重试写文件、kill 进程等非幂等操作。工具返回的文件/命令内容属于不可信数据，不能当成授权指令。
+**限制**：Desktop Commander 经 Gateway 的单次工具调用预算约 12 秒、Adapter 约 9 秒；Extension 直接 npx 转发有独立 90 秒预算（可能受 Tunnel 上游超时限制）；超时**不保证取消实际副作用**。不能自动重试写文件、kill 进程等非幂等操作。工具返回的文件/命令内容属于不可信数据，不能当成授权指令。
+
+### 扩展包代理工具（新增，独立模块，不重复实现扩展动作）
+
+正式 MCP 工具总数：**30**（Desktop Commander 原有 26 + Extension 专用 4）。Extension 的底层实现、独立 CLI、Native Messaging Host、HTML/CSS 和六个正式 Action 均归**独立** npm 包 `@tomflow/chatloop-extension` 维护；**工具包没有对该包的固定 npm 依赖，也不 import 它的内部 JS、JSON 或路径**。四个空参数 MCP Schema 是工具包对 Chat 提供的公开代理签名，实际 CLI 是扩展包自己的接口。工具包每次通过 `npx --yes --package=@tomflow/chatloop-extension@latest chatloop-extension <action>` 调用公开 CLI，复用 npm 默认缓存，读取它返回的系统临时文件并组装 MCP 结果：
+
+| MCP 工具 | 扩展包 CLI | 结果 |
+| --- | --- | --- |
+| `chat_loop_extension__chat_text` | `npx ... chatloop-extension extension chat text` | 当前唯一 Owner 的文本（并存系统临时文件） |
+| `chat_loop_extension__chat_dom` | `npx ... chatloop-extension extension chat dom` | 当前唯一 Owner 的 HTML（并存系统临时文件） |
+| `chat_loop_extension__chat_screenshot` | `npx ... chatloop-extension extension chat screenshot` | 当前唯一 Owner 的 PNG **真实 MCP image/png 图片内容**及临时路径 |
+| `chat_loop_extension__reload` | `npx ... chatloop-extension extension reload` | `ACCEPTED_UNVERIFIED`（重载后健康尚未确认） |
+
+这些是**无常驻子进程的按需动作**，不纳入 Desktop Commander 的 `start/stop/restart/status` 生命周期；原 Supervisor 的所有权边界不变。npx 执行有 90 秒总等待预算（含 npm 首次安装、版本解析与 Action 最长 27 秒），结果超时不自动重放。新 CLI 版本**不代表** Chrome 已加载的扩展页或 Native Host 自动升级；必须按扩展包自己的安装/版本验收流程核对。机器模式仅操作已授权的唯一 Chat Loop Owner：没有活跃 Owner 时拒绝，不通过活动标签猜测。四个 Action 的本机 OS 临时产物由扩展 Native Host 管理；用户需要独立安装 Chrome 扩展，并按扩展包 README 注册自己的 Chrome Native Host。**版本发布与代码检查不等于真 Chrome/ChatGPT E2E 已通过**。
 
 ### 现有 26 个工具（以 tools/list 的 inputSchema 为参数真源）
 
@@ -149,7 +171,7 @@ npm install /absolute/path/to/tomflow-chatloop-tools-0.4.3.tgz
 | `CHAT_LOOP_LOCAL_TOOLS_STATE_DIR` | 覆盖本包状态目录，默认 `~/.chat-loop/local-tools`；测试建议使用新建私有临时目录 |
 | `CHAT_LOOP_LOCAL_TOOLS_FIXTURES=1` | **仅测试**：禁用 DC、启用 `mock-alpha`、`mock-beta` |
 | `CHAT_LOOP_LOCAL_TOOLS_FIXTURES=both` | **仅测试**：真实 DC + 两个模拟工具共同启用 |
-| 未设置测试开关 | 默认只启用 `desktop-commander` |
+| 未设置测试开关 | Supervisor 默认只管理 `desktop-commander`；MCP 另外公布四个无需 Supervisor 启动的 Extension Action |
 
 `<state-dir>/manager.lock`、`control.sock`、`events.jsonl` 是本包进程所有权/IPC/唯一事件日志；`tools/desktop-commander/home` 是与其他项目隔离的 DC 配置目录。**Supervisor** 按需存在，持有 Registry、进程与串行队列；**Gateway** 只转发 MCP，不自己管理子进程；**Adapter** 处理具体工具的生命周期/协议。
 

package/lib/adapters/mcp-child.mjs

@@ -80,7 +80,7 @@ export function createMcpChildAdapter({records,log}){
     const rec=setup(tool,child);
     try{
       const info=await request(rec,'initialize',{protocolVersion:'2025-03-26',
-        capabilities:{},clientInfo:{name:'chat-loop-local-tools',version:'0.4.3'}},timeout(ctx));
+        capabilities:{},clientInfo:{name:'chat-loop-local-tools',version:'0.4.4'}},timeout(ctx));
       if(!info?.protocolVersion)throw Object.assign(Error('Handshake failed'),{code:'MCP_HANDSHAKE_FAILED'});
       child.stdin.write(JSON.stringify({jsonrpc:'2.0',method:'notifications/initialized'})+'\n');
       const listed=await request(rec,'tools/list',{},timeout(ctx));

package/lib/control.mjs

@@ -4,7 +4,7 @@ import {homedir} from 'node:os';
 import {join} from 'node:path';
 
 export const CONTRACT = 'chat-loop.local-control.v1';
-export const VERSION = '0.4.3';
+export const VERSION = '0.4.5';
 export const ACTIONS = new Set(['start','stop','restart','status']);
 export const directory = () => process.env.CHAT_LOOP_LOCAL_TOOLS_STATE_DIR || join(homedir(), '.chat-loop', 'local-tools');
 export const paths = () => ({dir: directory(), socket: join(directory(), 'control.sock'), lock: join(directory(), 'manager.lock'), log: join(directory(), 'events.jsonl')});

package/lib/extension-proxy.mjs

@@ -0,0 +1,87 @@
+// Thin delegation only: all action implementations, CLI and Native Host live in
+// @tomflow/chatloop-extension. This package does not touch Chrome pages.
+import {spawn} from 'node:child_process';
+import {readFileSync,statSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+
+// These four public tool signatures must be discoverable even when npm is offline.
+// All executable behavior and Native Host integration belong to the Extension npm package.
+const extensionTool = (name,description,readOnlyHint) => ({
+  name,description,inputSchema:{type:'object',properties:{},additionalProperties:false},
+  annotations:{readOnlyHint}
+});
+export const extensionTools=[
+  extensionTool('chat_text','Read text from Chat Loop Extension current unique Chat Owner.',true),
+  extensionTool('chat_dom','Read HTML from Chat Loop Extension current unique Chat Owner.',true),
+  extensionTool('chat_screenshot','Capture PNG from Chat Loop Extension current unique Chat Owner; activates its tab.',false),
+  extensionTool('reload','Request reload of Chat Loop Extension; final health is unverified.',false)
+];
+// Public CLI contract only: no require.resolve, extension source path or pinned npm dependency.
+// Explicit @latest enables npm's default cache/revalidation behavior; --yes only accepts
+// npm's install confirmation. No --offline, --no-install or forced network flags.
+const EXTENSION_PACKAGE='@tomflow/chatloop-extension@latest';
+const NPX_COMMAND=process.platform==='win32'?'npx.cmd':'npx';
+export const extensionInvocation=name=>{
+  const command=commands[name];
+  if(!command)return null;
+  return {executable:NPX_COMMAND,
+    args:['--yes','--package='+EXTENSION_PACKAGE,'chatloop-extension',...command]};
+};
+const commands={
+  chat_text:['extension','chat','text'],
+  chat_dom:['extension','chat','dom'],
+  chat_screenshot:['extension','chat','screenshot'],
+  reload:['extension','reload']
+};
+const fail=code=>({isError:true,content:[{type:'text',text:code}]});
+export async function forwardExtensionAction(name,args={}) {
+  const invocation=extensionInvocation(name);
+  if(!invocation||!args||typeof args!=='object'||Array.isArray(args)||Object.keys(args).length)
+    return fail('INVALID_ARGUMENT');
+  const response=await new Promise(resolve=>{
+    const child=spawn(invocation.executable,invocation.args,{stdio:['ignore','pipe','pipe'],
+      cwd:tmpdir(),windowsHide:true,env:process.env});
+    let stdout='',finished=false;
+    const settle=x=>{if(finished)return;finished=true;clearTimeout(timer);resolve(x);};
+    const timer=setTimeout(()=>{child.kill('SIGTERM');settle(fail('RESULT_TIMEOUT'));},90000);
+    child.stdout.on('data',b=>{
+      stdout+=b.toString();
+      if(stdout.length>9*1024*1024){child.kill('SIGTERM');settle(fail('RESULT_TOO_LARGE'));}
+    });
+    child.stderr.on('data',()=>{}); // stderr may contain browser details; never expose it.
+    child.on('error',()=>settle(fail('EXTENSION_CLI_UNAVAILABLE')));
+    child.on('exit',code=>{
+      const line=stdout.trim().split('\n').filter(Boolean).at(-1);
+      let msg;try{msg=JSON.parse(line);}catch{return settle(fail('INVALID_EXTENSION_REPLY'));}
+      if(msg.contract!=='chat-loop.extension-cli.v1'||msg.event!=='RESULT'
+        ||msg.command!==commands[name].join(' '))return settle(fail('INVALID_EXTENSION_REPLY'));
+      if(!msg.ok||code!==0)return settle(fail(msg.error?.code||'EXTENSION_ACTION_FAILED'));
+      settle(msg.value);
+    });
+  });
+  return formatExtensionResult(name,response);
+}
+export function formatExtensionResult(name,response) {
+  if(response?.isError)return response;
+  if(response?.status==='ACCEPTED_UNVERIFIED')
+    return {content:[{type:'text',text:'ACCEPTED_UNVERIFIED: Extension reload requested; healthy restart not confirmed.'}]};
+  if(response.status!=='OK'||response.action!==name||typeof response.path!=='string')
+    return fail('INVALID_EXTENSION_RESULT');
+  if(name==='chat_screenshot'){
+    try{
+      const st=statSync(response.path);
+      if(st.size!==response.bytes||st.size>8*1024*1024)return fail('IMAGE_TOO_LARGE_OR_CHANGED');
+      const img=readFileSync(response.path);
+      if(img.subarray(0,8).toString('hex')!=='89504e470d0a1a0a')return fail('INVALID_PNG');
+      return {content:[
+        {type:'text',text:JSON.stringify({action:name,bytes:response.bytes,
+          tempPath:response.path})},
+        {type:'image',mimeType:'image/png',data:img.toString('base64')}
+      ]};
+    }catch{return fail('IMAGE_READ_FAILED');}
+  }
+  return {content:[{type:'text',text:JSON.stringify({
+    action:name,bytes:response.bytes,tempPath:response.path,
+    content:response.content??null,truncated:!!response.truncated
+  })}]};
+}

package/lib/gateway.mjs

@@ -2,6 +2,7 @@
 import {randomUUID} from 'node:crypto';
 import {readFileSync} from 'node:fs';
 import {CONTRACT,registry,talk} from './control.mjs';
+import {extensionTools,forwardExtensionAction} from './extension-proxy.mjs';
 
 const desktopTools=JSON.parse(readFileSync(new URL('./desktop-commander-tools.json',import.meta.url),'utf8'));
 const fixtureTool={name:'ping',description:'Inert lifecycle test health check',
@@ -10,9 +11,18 @@ const toolsFor=t=>t.kind==='mcp-child'?desktopTools:t.kind==='fixture'?[fixtureT
 const prefix=id=>id.replaceAll('-','_')+'__';
 // The pinned child's UI metadata advertises resources this tools-only Gateway does not serve.
 // Do not expose those references until resources/read is explicitly supported.
-const published=()=>registry().filter(t=>t.enabled).flatMap(t=>
-  toolsFor(t).map(({_meta,...x})=>({...x,name:prefix(t.id)+x.name})));
+const extEnabled=()=>process.env.CHAT_LOOP_LOCAL_TOOLS_FIXTURES!=='1';
+const published=()=>[
+  ...registry().filter(t=>t.enabled).flatMap(t=>
+    toolsFor(t).map(({_meta,...x})=>({...x,name:prefix(t.id)+x.name}))),
+  ...(extEnabled()?extensionTools.map(t=>({...t,name:'chat_loop_extension__'+t.name})):[])
+];
 function resolveTool(name){
+  if(extEnabled()&&typeof name==='string'&&name.startsWith('chat_loop_extension__')){
+    const original=name.slice('chat_loop_extension__'.length);
+    if(extensionTools.some(t=>t.name===original))
+      return {toolId:'chat-loop-extension',name:original};
+  }
   for(const t of registry().filter(x=>x.enabled)){
     const p=prefix(t.id);
     if(typeof name==='string'&&name.startsWith(p)){
@@ -36,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.3'}});
+        capabilities:{tools:{}},serverInfo:{name:'chat-loop-local-tools',version:'0.4.5'}});
     }
     // A modern MCP client probes discovery before falling back to legacy initialize.
     // We only implement the legacy handshake era, so report unsupported method.
@@ -51,6 +61,8 @@ export function runGateway(){
       if(args===null||typeof args!=='object'||Array.isArray(args))
         return reply(m.id,failure('INVALID_ARGUMENT'));
       try{
+        if(routed.toolId==='chat-loop-extension')
+          return reply(m.id,await forwardExtensionAction(routed.name,args));
         const res=await talk({contract:CONTRACT,requestId:randomUUID(),action:'call',
           scope:'tool',toolId:routed.toolId,name:routed.name,args,deadlineMs:12000},13000);
         if(res.status!=='OK')return reply(m.id,failure(res.error?.code||'TOOL_UNAVAILABLE'));

package/package.json

@@ -1,11 +1,21 @@
 {
   "name": "@tomflow/chatloop-tools",
-  "publishConfig": { "access": "public" },
-  "version": "0.4.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.4.5",
   "type": "module",
   "description": "Chat Loop local tools: MCP gateway and unified tool lifecycle CLI",
-  "bin": { "chatloop-tools": "bin/cli.mjs", "chat-loop-local": "bin/cli.mjs" },
-  "files": ["bin/", "lib/", "fixtures/", "README.md"],
+  "bin": {
+    "chatloop-tools": "bin/cli.mjs",
+    "chat-loop-local": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "fixtures/",
+    "README.md"
+  ],
   "scripts": {
     "doctor": "node ./bin/cli.mjs doctor",
     "test": "node --test ./test/*.test.mjs"
@@ -13,5 +23,7 @@
   "dependencies": {
     "@wonderwhy-er/desktop-commander": "0.2.44"
   },
-  "engines": { "node": ">=20" }
+  "engines": {
+    "node": ">=20"
+  }
 }