@tomflow/chatloop-tools 0.0.0-stage → 0.4.0

package/lib/gateway.mjs

@@ -0,0 +1,71 @@
+// Stdio MCP entrypoint: protocol framing and routing only; never owns child processes.
+import {randomUUID} from 'node:crypto';
+import {readFileSync} from 'node:fs';
+import {CONTRACT,registry,talk} from './control.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',
+  inputSchema:{type:'object',properties:{},additionalProperties:false}};
+const toolsFor=t=>t.kind==='mcp-child'?desktopTools:t.kind==='fixture'?[fixtureTool]:[];
+const prefix=id=>id.replaceAll('-','_')+'__';
+const published=()=>registry().filter(t=>t.enabled).flatMap(t=>
+  toolsFor(t).map(x=>({...x,name:prefix(t.id)+x.name})));
+function resolveTool(name){
+  for(const t of registry().filter(x=>x.enabled)){
+    const p=prefix(t.id);
+    if(typeof name==='string'&&name.startsWith(p)){
+      const original=name.slice(p.length);
+      if(toolsFor(t).some(x=>x.name===original))return {toolId:t.id,name:original};
+    }
+  }
+  return null;
+}
+const failure=code=>({isError:true,content:[{type:'text',text:code}]});
+const rpcError=(code,message)=>({code,message});
+export function runGateway(){
+  let buf='',connected=false;
+  const write=message=>process.stdout.write(JSON.stringify(message)+'\n');
+  const reply=(id,result)=>write({jsonrpc:'2.0',id,result});
+  const reject=(id,code,message)=>write({jsonrpc:'2.0',id,error:rpcError(code,message)});
+  const processMessage=async m=>{
+    if(!m||m.jsonrpc!=='2.0'||m.id===undefined)return;
+    if(m.method==='initialize'){
+      if(!['2025-03-26','2024-11-05'].includes(m.params?.protocolVersion))
+        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.0'}});
+    }
+    if(!connected)return reject(m.id,-32002,'NOT_INITIALIZED');
+    if(m.method==='ping')return reply(m.id,{});
+    if(m.method==='tools/list')return reply(m.id,{tools:published()});
+    if(m.method==='tools/call'){
+      const routed=resolveTool(m.params?.name);
+      if(!routed)return reply(m.id,failure('UNKNOWN_TOOL'));
+      const args=m.params?.arguments??{};
+      if(args===null||typeof args!=='object'||Array.isArray(args))
+        return reply(m.id,failure('INVALID_ARGUMENT'));
+      try{
+        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'));
+        return reply(m.id,res.result);
+      }catch(e){
+        return reply(m.id,failure(['ENOENT','ECONNREFUSED'].includes(e.code)?'TOOL_UNAVAILABLE':
+          e.code||'MANAGER_UNAVAILABLE'));
+      }
+    }
+    return reject(m.id,-32601,'METHOD_NOT_FOUND');
+  };
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data',chunk=>{
+    buf+=chunk;
+    if(buf.length>1024*1024){process.stderr.write('MCP frame too large\n');process.exitCode=1;process.stdin.pause();return;}
+    let n;
+    while((n=buf.indexOf('\n'))>=0){
+      const line=buf.slice(0,n);buf=buf.slice(n+1);
+      let m;try{m=JSON.parse(line);}catch{continue;}
+      void processMessage(m).catch(e=>{if(m?.id!==undefined)reject(m.id,-32603,'INTERNAL_ERROR');});
+    }
+  });
+}

package/lib/supervisor.mjs

@@ -0,0 +1,163 @@
+import {randomUUID} from 'node:crypto';
+import {appendFileSync, closeSync, existsSync, openSync, readFileSync, unlinkSync, writeFileSync, chmodSync} from 'node:fs';
+import {createServer} from 'node:net';
+import {CONTRACT,VERSION,registry,paths,ensurePrivateDir,ACTIONS} from './control.mjs';
+import {createAdapter} from './adapters/index.mjs';
+
+const catalog=registry(), records=new Map(), queues=new Map(), seen=new Map();
+const p=paths(), nonce=randomUUID();
+let lockFd, server, idleTimer;
+const log=(event,detail={})=>{
+  try{appendFileSync(p.log,JSON.stringify({time:new Date().toISOString(),event,...detail})+'\n',{mode:0o600});}catch{}
+};
+const error=(code,message=code)=>({code,message});
+const after=rec=>rec ? rec.state : 'STOPPED';
+function serial(id,fn){
+  const prev=queues.get(id)||Promise.resolve();
+  const next=prev.catch(()=>{}).then(fn);
+  queues.set(id,next);
+  next.finally(()=>{if(queues.get(id)===next)queues.delete(id);}).catch(()=>{});
+  return next;
+}
+const adapters=new Map();
+function adapterFor(tool){
+  if(!adapters.has(tool.kind))adapters.set(tool.kind,createAdapter(tool.kind,{records,log}));
+  return adapters.get(tool.kind);
+}
+function targets(req){
+  const found=req.scope==='tool'?catalog.filter(t=>t.id===req.toolId):
+    catalog.filter(t=>req.action==='status'||t.enabled);
+  if(req.scope==='tool' && !found.length)throw error('UNKNOWN_TOOL');
+  if(req.action!=='status' && found.some(t=>!t.enabled))throw error('DISABLED_TOOL');
+  if(req.action!=='status' && !found.length)throw error('NO_ENABLED_TOOLS');
+  return found;
+}
+const bad=(req,code)=>({contract:CONTRACT,requestId:req?.requestId||null,action:req?.action||null,
+  scope:req?.scope||null,target:req?.toolId||null,status:'FAILED',results:[],error:error(code)});
+async function executeCall(req){
+  const invalid=()=>bad(req,'INVALID_ARGUMENT');
+  if(req.contract!==CONTRACT)return bad(req,'INCOMPATIBLE_VERSION');
+  if(typeof req.requestId!=='string'||req.requestId.length<6||req.requestId.length>128||
+     req.scope!=='tool'||typeof req.toolId!=='string'||typeof req.name!=='string'||
+     !req.args||typeof req.args!=='object'||Array.isArray(req.args)||
+     !Number.isInteger(req.deadlineMs)||req.deadlineMs<1000||req.deadlineMs>30000)return invalid();
+  const tool=catalog.find(t=>t.id===req.toolId);
+  if(!tool)return bad(req,'UNKNOWN_TOOL');
+  if(!tool.enabled)return bad(req,'DISABLED_TOOL');
+  const argsKey=JSON.stringify([req.action,req.scope,req.toolId,req.name,req.args,req.deadlineMs]);
+  const prev=seen.get(req.requestId);
+  if(prev)return prev.payload===argsKey?prev.promise:bad(req,'REQUEST_ID_REUSE');
+  const expires=Date.now()+req.deadlineMs;
+  const promise=serial(tool.id,async()=>{
+    try{
+      const adapter=adapterFor(tool);
+      if(typeof adapter.call!=='function')return bad(req,'TOOL_UNAVAILABLE');
+      const value=await adapter.call(tool,req.name,req.args,
+        {requestId:req.requestId,remaining:()=>Math.max(0,expires-Date.now())});
+      log('tool-call',{requestId:req.requestId,toolId:tool.id,toolName:req.name,status:'OK'});
+      return {contract:CONTRACT,requestId:req.requestId,status:'OK',result:value};
+    }catch(e){
+      const code=e.code||'UNKNOWN_RESULT';
+      log('tool-call',{requestId:req.requestId,toolId:tool.id,toolName:req.name,status:'FAILED',errorCode:code});
+      return bad(req,code);
+    }
+  });
+  seen.set(req.requestId,{payload:argsKey,promise});
+  if(seen.size>128)seen.delete(seen.keys().next().value);
+  return promise;
+}
+async function execute(req){
+  if(req.contract!==CONTRACT)return bad(req,'INCOMPATIBLE_VERSION');
+  if(typeof req.requestId!=='string'||req.requestId.length<6||req.requestId.length>128||
+     !ACTIONS.has(req.action)||!['all','tool'].includes(req.scope)||
+     (req.scope==='tool' && typeof req.toolId!=='string')||
+     (req.scope==='all' && req.toolId!==undefined)||
+     !Number.isInteger(req.deadlineMs)||req.deadlineMs<1000||req.deadlineMs>30000)return bad(req,'INVALID_ARGUMENT');
+  let found;try{found=targets(req);}catch(e){return bad(req,e.code);}
+  const payload=JSON.stringify([req.action,req.scope,req.toolId||null,req.deadlineMs]);
+  const hit=seen.get(req.requestId);
+  if(hit)return hit.payload===payload?hit.promise:bad(req,'REQUEST_ID_REUSE');
+  // Read-only status must never cancel idle shutdown.
+  if(req.action==='start'||req.action==='restart')clearTimeout(idleTimer);
+  const expiresAt=Date.now()+req.deadlineMs;
+  const ctx={requestId:req.requestId,remaining:()=>Math.max(0,expiresAt-Date.now())};
+  const promise=(async()=>{
+    const results=[];
+    // Batch targets run in Registry order; each tool is separately serialized.
+    for(const t of found){
+      const item=await serial(t.id,async()=>{
+        if(req.action==='status'){
+          if(!t.enabled)return {toolId:t.id,enabled:false,before:'DISABLED',after:'DISABLED',
+            outcome:'OBSERVED',pid:null,evidence:'REGISTRY',error:null};
+          return adapterFor(t).inspect(t,ctx);
+        }
+        if(req.action==='start')return adapterFor(t).launch(t,ctx);
+        if(req.action==='stop')return adapterFor(t).stop(t,ctx);
+        const ended=await adapterFor(t).stop(t,ctx);
+        if(ended.error)return {...ended,outcome:'RESTART_FAILED'};
+        const began=await adapterFor(t).launch(t,ctx);
+        return {...began,before:ended.before,outcome:began.error?'RESTART_FAILED':'RESTARTED'};
+      });
+      results.push(item);
+    }
+    const failures=results.filter(r=>r.error);
+    const status=results.some(r=>r.after==='UNKNOWN')?'UNKNOWN':failures.length===0?'OK':failures.length===results.length?'FAILED':'PARTIAL';
+    const response={contract:CONTRACT,requestId:req.requestId,action:req.action,scope:req.scope,target:req.toolId||null,status,results,managerPid:process.pid};
+    log('control',{requestId:req.requestId,action:req.action,scope:req.scope,toolId:req.toolId||null,status,
+      results:results.map(r=>({toolId:r.toolId,after:r.after,outcome:r.outcome,errorCode:r.error?.code||null}))});
+    if(req.action==='stop' && ![...records.values()].some(r=>!r.exited)){
+      idleTimer=setTimeout(()=>shutdown(),3000);idleTimer.unref();
+    }
+    return response;
+  })();
+  seen.set(req.requestId,{payload,promise});
+  if(seen.size>128)seen.delete(seen.keys().next().value);
+  return promise;
+}
+async function shutdown(){
+  if([...records.values()].some(r=>!r.exited))return;
+  server?.close();
+  try{if(existsSync(p.socket))unlinkSync(p.socket);}catch{}
+  try{if(existsSync(p.lock) && JSON.parse(readFileSync(p.lock,'utf8')).nonce===nonce)unlinkSync(p.lock);}catch{}
+  try{if(lockFd!==undefined)closeSync(lockFd);}catch{}
+  process.exit(0);
+}
+async function main(){
+  ensurePrivateDir();
+  try{lockFd=openSync(p.lock,'wx',0o600);}
+  catch(err){if(err.code==='EEXIST')process.exit(0);throw err;}
+  writeFileSync(lockFd,JSON.stringify({pid:process.pid,nonce,version:VERSION,at:Date.now()}));
+  // A lock ensures no other manager may own this socket.
+  if(existsSync(p.socket)){
+    const s=(await import('node:fs')).lstatSync(p.socket);
+    if(!s.isSocket() || (process.getuid && s.uid!==process.getuid()))throw Error('Unknown socket ownership');
+    unlinkSync(p.socket);
+  }
+  server=createServer(socket=>{
+    let buf='', handled=false;
+    socket.on('data',chunk=>{
+      if(handled)return;
+      buf+=chunk.toString();
+      if(buf.length>1048576){socket.destroy();return;}
+      const n=buf.indexOf('\n');if(n<0)return;
+      handled=true;
+      let req;try{req=JSON.parse(buf.slice(0,n));}catch{socket.end(JSON.stringify(bad({},'INVALID_ARGUMENT'))+'\n');return;}
+      const work=req?.action==='__ping'?
+        Promise.resolve({contract:CONTRACT,version:VERSION,registrySignature:catalog.map(t=>t.id+':'+t.enabled).join('|'),ownerNonce:nonce,managerPid:process.pid}):req?.action==='call'?executeCall(req):execute(req);
+      work.then(value=>socket.end(JSON.stringify(value)+'\n')).catch(err=>{
+        log('ipc-error',{code:err.code||'INTERNAL_ERROR'});
+        socket.end(JSON.stringify(bad(req,'INTERNAL_ERROR'))+'\n');
+      });
+    });
+    socket.on('error',()=>{});
+  });
+  await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(p.socket,resolve);});
+  chmodSync(p.socket,0o600);
+  log('manager-start',{pid:process.pid,version:VERSION});
+  process.on('SIGTERM',async()=>{
+    for(const t of catalog.filter(t=>t.enabled))
+      await serial(t.id,()=>adapterFor(t).stop(t,{requestId:'manager-shutdown',remaining:()=>5000}));
+    await shutdown();
+  });
+}
+main().catch(err=>{log('manager-fatal',{code:err.code||'ERROR'});process.exit(1);});

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "@tomflow/chatloop-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "publishConfig": { "access": "public" },
+  "version": "0.4.0",
+  "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"],
+  "scripts": {
+    "doctor": "node ./bin/cli.mjs doctor",
+    "test": "node --test ./test/*.test.mjs"
+  },
+  "dependencies": {
+    "@wonderwhy-er/desktop-commander": "0.2.44"
+  },
+  "engines": { "node": ">=20" }
+}