@yanglaofish/fishtools 0.5.2 → 0.6.0

package/node_modules/@mytools/fst-logs/src/run-logs.js

@@ -5,6 +5,7 @@ import {markdownHeader,markdownEvent,markdownResult} from './markdown-log.js';
 import {logPolicy,jsonSize,eventPreview} from './log-bounds.js';
 import {createStepSummaries} from './step-summaries.js';
 import {previewRun} from './run-preview.js';
+import {samePathFileIdentity} from './file-identity.js';
 
 const validId=id=>typeof id==='string'&&/^[a-f0-9-]{36}$/.test(id);
 const logFiles=['run.md','events.jsonl','result.json','run.meta.json'];
@@ -33,9 +34,9 @@ export function createRunLogs(directory,{projectDir,allowLegacy=false,...options
     return dir;
   }
   async function safeFile(file){
-    const before=await lstat(file);if(!before.isFile()||before.isSymbolicLink())throw new FlowError('日志文件无效');
+    const before=await lstat(file,{bigint:true});if(!before.isFile()||before.isSymbolicLink())throw new FlowError('日志文件无效');
     const handle=await open(file,'r');
-    try{const after=await handle.stat();if(!after.isFile()||before.ino!==after.ino||before.dev!==after.dev)throw new FlowError('日志文件无效');return handle;}
+    try{const after=await handle.stat({bigint:true});if(!after.isFile()||!(await samePathFileIdentity(file,before,after)))throw new FlowError('日志文件无效');return handle;}
     catch(error){await handle.close();throw error;}
   }
   async function read(id){

package/node_modules/@mytools/fst-logs/src/session-history.js

@@ -0,0 +1,180 @@
+import path from 'node:path';
+import {constants} from 'node:fs';
+import {lstat,mkdir,open,readdir,rename,unlink} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {FlowError} from '@mytools/sdk';
+import {jsonSize} from './log-bounds.js';
+import {samePathFileIdentity} from './file-identity.js';
+
+const validId=id=>typeof id==='string'&&/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(id);
+const normalize=directory=>process.platform==='win32'?path.resolve(directory).toLowerCase():path.resolve(directory);
+const queues=new Map();
+const decoder=new TextDecoder('utf-8',{fatal:true});
+const failure=(message,code,cause)=>new FlowError(message,{code,cause});
+const plain=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+
+function checkId(id){if(!validId(id))throw failure('会话 ID 无效','SESSION_ID_INVALID');}
+function checkSnapshot(record,id){
+  if(!plain(record)||record.schemaVersion!==1||record.id!==id||!Number.isFinite(Date.parse(record.startedAt))||!Number.isFinite(Date.parse(record.updatedAt))||Date.parse(record.updatedAt)<Date.parse(record.startedAt)||!Array.isArray(record.commandHistory)||!record.commandHistory.every(command=>typeof command==='string')||!Array.isArray(record.feed))throw failure('会话元数据格式无效','SESSION_RECORD_INVALID');
+  if(record.resumedFrom!==undefined&&(!validId(record.resumedFrom)||record.resumedFrom===id))throw failure('会话恢复来源 ID 无效','SESSION_RECORD_INVALID');
+}
+function encoded(value,limit,code){
+  try{
+    // 预估器会多计容器末尾分隔符，先用双倍预算拒绝巨大输入，再按实际 JSON 字节精确判断。
+    if(jsonSize(value,limit*2)>limit*2)throw failure('会话记录超过字节预算',code);
+    const text=JSON.stringify(value);
+    if(typeof text!=='string')throw failure('会话记录必须可以序列化为 JSON','SESSION_RECORD_INVALID');
+    if(Buffer.byteLength(text)>limit)throw failure('会话记录超过字节预算',code);
+    return text;
+  }catch(error){if(error instanceof FlowError)throw error;throw failure('会话记录不能序列化为 JSON','SESSION_RECORD_INVALID',error);}
+}
+function parsed(buffer){
+  try{return JSON.parse(decoder.decode(buffer));}
+  catch(error){throw failure('会话记录损坏或不是有效的 UTF-8 JSON','SESSION_RECORD_INVALID',error);}
+}
+
+export function createSessionHistory(directory,{projectDir,maxBytes=2*1024*1024,maxEntryBytes=65536,maxPageBytes=512*1024,maxPendingBytes=8*1024*1024}={}){
+  if(typeof directory!=='string'||!directory||typeof projectDir!=='string'||!projectDir)throw failure('会话目录和工作区目录必须为非空路径','SESSION_PATH_INVALID');
+  const policy={maxBytes,maxEntryBytes,maxPageBytes,maxPendingBytes};
+  for(const [key,value] of Object.entries(policy))if(!Number.isSafeInteger(value)||value<2)throw failure(`会话 ${key} 必须为至少 2 的整数字节数`,'SESSION_RECORD_INVALID');
+  if(maxPageBytes<maxEntryBytes+1)throw failure('会话分页预算必须容纳一条记录及换行','SESSION_PAGE_LIMIT');
+  const root=path.resolve(directory),owner=normalize(projectDir);
+  const location=(id,suffix)=>{checkId(id);return path.join(root,`${id}.${suffix}`);};
+
+  function queue(id,bytes,operation){
+    checkId(id);const key=`${normalize(root)}\0${id}`;
+    let state=queues.get(key);
+    if(!state)state={tail:Promise.resolve(),bytes:0,jobs:0};
+    if(state.bytes+bytes>maxPendingBytes)return Promise.reject(failure('会话待写队列超过字节预算','SESSION_QUEUE_LIMIT'));
+    queues.set(key,state);
+    state.bytes+=bytes;state.jobs++;
+    const job=state.tail.then(operation).finally(()=>{state.bytes-=bytes;state.jobs--;if(!state.jobs&&queues.get(key)===state)queues.delete(key);});
+    // 一次失败只影响对应调用，后续操作仍可以读取原文件或重试。
+    state.tail=job.catch(()=>{});return job;
+  }
+  async function safeRoot(create=false){
+    if(create)await mkdir(root,{recursive:true});
+    const stat=await lstat(root);
+    if(!stat.isDirectory()||stat.isSymbolicLink())throw failure('会话根目录无效，不能使用目录链接','SESSION_PATH_INVALID');
+  }
+  async function regular(file,missing=false){
+    let stat;
+    try{stat=await lstat(file,{bigint:true});}catch(error){if(missing&&error.code==='ENOENT')return null;throw error;}
+    if(!stat.isFile()||stat.isSymbolicLink())throw failure('会话文件无效，不能使用文件链接','SESSION_PATH_INVALID');
+    return stat;
+  }
+  async function safeFile(file,{append=false}={}){
+    const before=await regular(file,append);
+    const flags=(append?constants.O_RDWR|constants.O_APPEND|constants.O_CREAT:constants.O_RDONLY)|(constants.O_NOFOLLOW??0);
+    const handle=await open(file,flags,0o600);
+    try{
+      const after=await handle.stat({bigint:true}),current=await regular(file);
+      if(!after.isFile()||(before&&!(await samePathFileIdentity(file,before,after)))||!(await samePathFileIdentity(file,current,after)))throw failure('会话文件在访问期间发生替换','SESSION_PATH_INVALID');
+      return handle;
+    }catch(error){await handle.close();throw error;}
+  }
+  async function readRecord(id){
+    checkId(id);await safeRoot();const handle=await safeFile(location(id,'json'));
+    let record;
+    try{
+      const size=(await handle.stat()).size;
+      if(size>maxBytes)throw failure('会话元数据超过读取字节预算','SESSION_METADATA_LIMIT');
+      const buffer=Buffer.alloc(Math.min(size+1,maxBytes+1));let offset=0;
+      while(offset<buffer.length){const {bytesRead}=await handle.read(buffer,offset,buffer.length-offset,offset);if(!bytesRead)break;offset+=bytesRead;}
+      if(offset>maxBytes)throw failure('会话元数据超过读取字节预算','SESSION_METADATA_LIMIT');
+      record=parsed(buffer.subarray(0,offset));
+    }finally{await handle.close();}
+    checkSnapshot(record,id);
+    if(record.sessionOwner!==owner)throw failure('会话记录不属于此工作区','SESSION_OWNER_MISMATCH');
+    return record;
+  }
+  async function saveRecord(record,text){
+    await safeRoot(true);
+    let existing;
+    try{existing=await readRecord(record.id);}catch(error){if(error.code!=='ENOENT')throw error;}
+    if(existing){
+      if(existing.startedAt!==record.startedAt)throw failure('已有会话的开始时间不能改变；恢复会话请使用新 ID','SESSION_RECORD_INVALID');
+      if(Date.parse(record.updatedAt)<Date.parse(existing.updatedAt))return existing;
+    }else{
+      // 缺少元数据的旧追加日志也不能被新会话接管。
+      if(await regular(location(record.id,'jsonl'),true))throw failure('会话追加日志已存在但缺少有效元数据，请使用新 ID','SESSION_RECORD_INVALID');
+    }
+    const target=location(record.id,'json'),temporary=path.join(root,`.${record.id}.${randomUUID()}.tmp`);
+    let handle;
+    try{
+      handle=await open(temporary,'wx',0o600);await handle.writeFile(text,'utf8');await handle.sync();await handle.close();handle=null;
+      await safeRoot();await regular(target,true);await rename(temporary,target);
+    }finally{if(handle)await handle.close();try{await unlink(temporary);}catch(error){if(error.code!=='ENOENT')throw error;}}
+    return record;
+  }
+  async function appendRecord(id,text){
+    await readRecord(id);await safeRoot();const handle=await safeFile(location(id,'jsonl'),{append:true});
+    try{
+      const size=(await handle.stat()).size;
+      if(size){const last=Buffer.alloc(1);await handle.read(last,0,1,size-1);if(last[0]!==10)throw failure('会话追加日志末尾存在未完成记录，拒绝继续写入','SESSION_RECORD_INVALID');}
+      await handle.writeFile(text+'\n','utf8');await handle.sync();
+    }finally{await handle.close();}
+  }
+  async function readPage(id,{cursor=0,limit=100}={}){
+    if(!Number.isSafeInteger(cursor)||cursor<0)throw failure('会话 cursor 必须为非负整数字节位置','SESSION_CURSOR_INVALID');
+    if(!Number.isSafeInteger(limit)||limit<1)throw failure('会话 limit 必须为正整数条目数','SESSION_PAGE_LIMIT');
+    limit=Math.min(limit,200);await readRecord(id);
+    let handle;
+    try{handle=await safeFile(location(id,'jsonl'));}
+    catch(error){if(error.code!=='ENOENT')throw error;if(cursor!==0)throw failure('会话 cursor 超过记录长度','SESSION_CURSOR_INVALID');return {entries:[],cursor,nextCursor:0,hasMore:false,totalBytes:0};}
+    try{
+      const totalBytes=(await handle.stat()).size;
+      if(cursor>totalBytes)throw failure('会话 cursor 超过记录长度','SESSION_CURSOR_INVALID');
+      if(cursor){const previous=Buffer.alloc(1);await handle.read(previous,0,1,cursor-1);if(previous[0]!==10)throw failure('会话 cursor 必须位于完整记录边界','SESSION_CURSOR_INVALID');}
+      const buffer=Buffer.alloc(Math.min(maxPageBytes+1,totalBytes-cursor));let readBytes=0;
+      while(readBytes<buffer.length){const {bytesRead}=await handle.read(buffer,readBytes,buffer.length-readBytes,cursor+readBytes);if(!bytesRead)break;readBytes+=bytesRead;}
+      let offset=0;const entries=[];
+      while(offset<readBytes&&entries.length<limit){
+        const newline=buffer.indexOf(10,offset);
+        if(newline===-1||newline>=readBytes){
+          if(readBytes-offset>maxEntryBytes)throw failure('会话单条记录超过读取字节预算','SESSION_ENTRY_LIMIT');
+          if(cursor+readBytes<totalBytes&&entries.length)break;
+          throw failure('会话追加日志存在未完成记录','SESSION_RECORD_INVALID');
+        }
+        if(newline-offset>maxEntryBytes)throw failure('会话单条记录超过读取字节预算','SESSION_ENTRY_LIMIT');
+        if(newline+1>maxPageBytes)break;
+        const entry=parsed(buffer.subarray(offset,newline));
+        if(!plain(entry))throw failure('会话追加记录必须为 JSON 对象','SESSION_RECORD_INVALID');
+        entries.push(entry);offset=newline+1;
+      }
+      const nextCursor=cursor+offset;
+      return {entries,cursor,nextCursor,hasMore:nextCursor<totalBytes,totalBytes};
+    }finally{await handle.close();}
+  }
+
+  return {
+    owner,policy:Object.freeze({...policy}),
+    async save(snapshot){
+      checkId(snapshot?.id);checkSnapshot(snapshot,snapshot.id);
+      const text=encoded({...snapshot,sessionOwner:owner},maxBytes,'SESSION_METADATA_LIMIT'),record=JSON.parse(text);
+      checkSnapshot(record,record.id);return queue(record.id,Buffer.byteLength(text),()=>saveRecord(record,text));
+    },
+    async read(id){checkId(id);return queue(id,0,()=>readRecord(id));},
+    async list(){
+      let entries;
+      try{await safeRoot();entries=await readdir(root,{withFileTypes:true});}catch(error){if(error.code==='ENOENT')return [];throw error;}
+      const records=[];
+      for(const entry of entries){
+        if(!entry.isFile()||!entry.name.endsWith('.json'))continue;
+        const id=entry.name.slice(0,-5);if(!validId(id))continue;
+        try{
+          const record=await queue(id,0,()=>readRecord(id));
+          records.push({schemaVersion:1,id,sessionOwner:record.sessionOwner,startedAt:record.startedAt,updatedAt:record.updatedAt,...(record.resumedFrom?{resumedFrom:record.resumedFrom}:{}),commandCount:record.commandHistory.length,feedCount:record.feed.length});
+        }catch(error){if(error.code==='EACCES'||error.code==='EPERM')throw error;}
+      }
+      return records.sort((a,b)=>Date.parse(b.updatedAt)-Date.parse(a.updatedAt)||b.id.localeCompare(a.id));
+    },
+    async append(id,entry){
+      checkId(id);if(!plain(entry))throw failure('会话追加记录必须为 JSON 对象','SESSION_RECORD_INVALID');
+      const text=encoded(entry,maxEntryBytes,'SESSION_ENTRY_LIMIT');
+      if(!plain(JSON.parse(text)))throw failure('会话追加记录必须为 JSON 对象','SESSION_RECORD_INVALID');
+      return queue(id,Buffer.byteLength(text)+1,()=>appendRecord(id,text));
+    },
+    async page(id,options={}){checkId(id);return queue(id,0,()=>readPage(id,options));},
+  };
+}

package/node_modules/@mytools/fst-platform/README.md

@@ -12,6 +12,7 @@
 | 导入路径 | 实现位置 |
 | --- | --- |
 | `@mytools/fst-platform` | `./src/process.js` |
+| `@mytools/fst-platform/managed-process` | `./src/managed-process.js` |
 | `@mytools/fst-platform/environments` | `./src/environments.js` |
 | `@mytools/fst-platform/bundle` | `./src/bundle.js` |
 | `@mytools/fst-platform/json` | `./src/json.js` |
@@ -37,9 +38,17 @@ node --test tests/modules.test.js tests/process.test.js tests/environments.test.
 
 ## 子进程环境
 
+`createProcessRunner({execute=runProcess,signal,log,audience})` 是内核调用方共用的受管包装，返回签名兼容 `runProcess(file,args,options)` 的函数。每次调用独立生成 `processId`，先写指令日志再执行自定义 onStart，先写输出日志再执行自定义 onOutput；合并调用级与上下文取消信号，不改变底层并发。插件经宿主 `ctx.runProcess` 使用，不能直接导入本入口代替上下文。权限检查由 plugin 负责，本包装不授予权限、不进行命令黑名单拦截。
+
+受管调用可指定 `logPolicy:false` 隐藏自动记录的参数与脚本，或 `{redactArgs:[零起算下标],omitArgs:true,omitScript:true}` 按需选择；实际参数和调用方 onStart 保留原值。有参数被隐藏时脚本也隐藏。无效策略执行前拒绝。该策略不自动识别密钥、不处理插件主动输出及已有日志；平台自动生成的进程启动失败信息也不再拼接 Execa 的完整命令行。
+
 `/shell` 的 `runShell(script,{shell='auto',runProcess,temporaryDir,...processOptions})` 使用唯一临时脚本文件，避免长脚本超过系统命令行长度上限，运行结束后删除本次文件。默认 Windows PowerShell / Linux sh，可选 powershell、pwsh、sh、bash；PowerShell 使用 UTF-8 BOM，其他 Shell 使用无 BOM UTF-8。插件传入 `ctx.runProcess` 与 `temporaryDir:ctx.outputDir`，保留当前代理、取消与日志规则，并兼容只读包目录。`shellInvocation` 保留构造简短命令参数的兼容接口。
 
+Windows 的 `shell:'auto'` 对单行 `ipconfig` / `ipconfig.exe` 及其字面量参数（如 `ipconfig /all`）直接执行系统目录中的 `ipconfig.exe`，读取当前系统 OEM 代码页后统一解码结果和实时输出。自动适配限于 TextDecoder 支持的 OEM 866、874、932、936、949、950、65001；中文 Windows 的 OEM 936 使用 GBK。代码页探测失败或代码页不受支持（如 437、850）时保留原 Shell 路径。变量、管道、多行、重定向等脚本继续按原 PowerShell 语义执行；复杂脚本中的旧编码与 UTF-8 混合输出没有自动转码。`onStart` 的 `script` 字段保留用户原始指令，直接执行的简单命令同时记录实际程序路径和参数。
+
 `runProcess(file,args,{env,extendEnv=true})` 默认把 `env` 覆盖到宿主环境上。
+
+可选 `onStart({file,args,cwd,script?})` 在程序路径解析后、实际启动前调用并等待完成；回调失败或此时取消不会启动子进程。`args` 使用独立数组，`cwd` 是实际绝对目录，`commandText` 可补充原始 Shell 指令。宿主通过该接口保存过程记录，执行结果与输出编码仍由原有接口返回。
 当调用方已按动作代理规则构造完整环境时，传 `extendEnv:false`，防止已移除的代理变量被重新继承。
 
 缓冲模式由平台按每条输出流的原始字节计算 `maxBuffer`，默认每条流 4 MiB；超限返回 `OUTPUT_LIMIT`。

package/node_modules/@mytools/fst-platform/node_modules/undici/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Matteo Collina and Undici contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/{undici/docs/docs/index.md → @mytools/fst-platform/node_modules/undici/README.md}

@@ -1,7 +1,5 @@
 # undici
 
-<!--type=misc-->
-
 [![Node CI](https://github.com/nodejs/undici/actions/workflows/ci.yml/badge.svg)](https://github.com/nodejs/undici/actions/workflows/nodejs.yml) [![neostandard javascript style](https://img.shields.io/badge/neo-standard-7fffff?style=flat\&labelColor=ff80ff)](https://github.com/neostandard/neostandard) [![npm version](https://badge.fury.io/js/undici.svg)](https://badge.fury.io/js/undici) [![codecov](https://codecov.io/gh/nodejs/undici/branch/main/graph/badge.svg?token=yZL6LtXkOA)](https://codecov.io/gh/nodejs/undici)
 
 An HTTP/1.1 client, written from scratch for Node.js.
@@ -17,71 +15,34 @@ Looking to contribute? Start by reading the [contributing guide](./CONTRIBUTING.
 
 ## Install
 
-```bash
+```
 npm i undici
 ```
 
 ## Benchmarks
 
-The benchmark is a simple getting data [example](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark.js) using
-50 TCP connections with a pipelining depth of 10 running on Node 24.14.1.
+The benchmark is a simple getting data [example](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark.js) using a
+50 TCP connections with a pipelining depth of 10 running on Node 22.11.0.
 
-### HTTP/1.1
-
-```text
+```
 ┌────────────────────────┬─────────┬────────────────────┬────────────┬─────────────────────────┐
 │  Tests                 │ Samples │ Result             │ Tolerance  │ Difference with slowest │
 ├────────────────────────┼─────────┼────────────────────┼────────────┼─────────────────────────┤
-│  'node-fetch'          │ 50      │ '4711.86 req/sec'  │ '± 2.92 %' │ '-'                     │
-│  'undici - fetch'      │ 75      │ '5438.50 req/sec'  │ '± 2.97 %' │ '+ 15.42 %'             │
-│  'axios'               │ 45      │ '5448.08 req/sec'  │ '± 2.98 %' │ '+ 15.62 %'             │
-│  'request'             │ 65      │ '5809.63 req/sec'  │ '± 2.90 %' │ '+ 23.30 %'             │
-│  'http - no keepalive' │ 35      │ '5910.77 req/sec'  │ '± 2.87 %' │ '+ 25.44 %'             │
-│  'got'                 │ 50      │ '6047.80 req/sec'  │ '± 2.91 %' │ '+ 28.35 %'             │
-│  'superagent'          │ 60      │ '7534.53 req/sec'  │ '± 2.97 %' │ '+ 59.91 %'             │
-│  'http - keepalive'    │ 75      │ '9343.41 req/sec'  │ '± 2.90 %' │ '+ 98.30 %'             │
-│  'undici - pipeline'   │ 65      │ '13470.70 req/sec' │ '± 2.93 %' │ '+ 185.89 %'            │
-│  'undici - request'    │ 80      │ '16850.87 req/sec' │ '± 2.93 %' │ '+ 257.63 %'            │
-│  'undici - stream'     │ 101     │ '18488.56 req/sec' │ '± 3.81 %' │ '+ 292.38 %'            │
-│  'undici - dispatch'   │ 101     │ '20786.44 req/sec' │ '± 3.08 %' │ '+ 341.15 %'            │
+│  'axios'               │ 15      │ '5708.26 req/sec'  │ '± 2.91 %' │ '-'                     │
+│  'http - no keepalive' │ 10      │ '5809.80 req/sec'  │ '± 2.30 %' │ '+ 1.78 %'              │
+│  'request'             │ 30      │ '5828.80 req/sec'  │ '± 2.91 %' │ '+ 2.11 %'              │
+│  'undici - fetch'      │ 40      │ '5903.78 req/sec'  │ '± 2.87 %' │ '+ 3.43 %'              │
+│  'node-fetch'          │ 10      │ '5945.40 req/sec'  │ '± 2.13 %' │ '+ 4.15 %'              │
+│  'got'                 │ 35      │ '6511.45 req/sec'  │ '± 2.84 %' │ '+ 14.07 %'             │
+│  'http - keepalive'    │ 65      │ '9193.24 req/sec'  │ '± 2.92 %' │ '+ 61.05 %'             │
+│  'superagent'          │ 35      │ '9339.43 req/sec'  │ '± 2.95 %' │ '+ 63.61 %'             │
+│  'undici - pipeline'   │ 50      │ '13364.62 req/sec' │ '± 2.93 %' │ '+ 134.13 %'            │
+│  'undici - stream'     │ 95      │ '18245.36 req/sec' │ '± 2.99 %' │ '+ 219.63 %'            │
+│  'undici - request'    │ 50      │ '18340.17 req/sec' │ '± 2.84 %' │ '+ 221.29 %'            │
+│  'undici - dispatch'   │ 40      │ '22234.42 req/sec' │ '± 2.94 %' │ '+ 289.51 %'            │
 └────────────────────────┴─────────┴────────────────────┴────────────┴─────────────────────────┘
 ```
 
-### HTTP/1.1 over HTTPS
-
-Using [benchmark-https.js](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark-https.js) against an h1-over-TLS server (50 connections, pipelining depth 10, Node 24.14.1).
-
-```text
-┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐
-│  Tests                 │ Samples │ Result            │ Tolerance  │ Difference with slowest │
-├────────────────────────┼─────────┼───────────────────┼────────────┼─────────────────────────┤
-│  'https - no keepalive'│ 10      │ '1358.40 req/sec' │ '± 1.99 %' │ '-'                     │
-│  'undici - fetch'      │ 30      │ '3721.76 req/sec' │ '± 2.97 %' │ '+ 173.98 %'            │
-│  'https - keepalive'   │ 35      │ '5633.91 req/sec' │ '± 2.84 %' │ '+ 314.75 %'            │
-│  'undici - pipeline'   │ 15      │ '6254.05 req/sec' │ '± 2.80 %' │ '+ 360.40 %'            │
-│  'undici - request'    │ 25      │ '6669.80 req/sec' │ '± 2.73 %' │ '+ 391.01 %'            │
-│  'undici - stream'     │ 25      │ '7019.04 req/sec' │ '± 2.77 %' │ '+ 416.71 %'            │
-│  'undici - dispatch'   │ 20      │ '7361.85 req/sec' │ '± 2.90 %' │ '+ 441.95 %'            │
-└────────────────────────┴─────────┴───────────────────┴────────────┴─────────────────────────┘
-```
-
-### HTTP/2
-
-Using [benchmark-http2.js](https://github.com/nodejs/undici/blob/main/benchmarks/benchmark-http2.js) against an h2 server (50 connections, pipelining depth 10, Node 24.14.1).
-
-```text
-┌────────────────────────┬─────────┬───────────────────┬────────────┬─────────────────────────┐
-│  Tests                 │ Samples │ Result            │ Tolerance  │ Difference with slowest │
-├────────────────────────┼─────────┼───────────────────┼────────────┼─────────────────────────┤
-│  'undici - fetch'      │ 45      │ '3499.03 req/sec' │ '± 2.93 %' │ '-'                     │
-│  'native - http2'      │ 25      │ '4904.58 req/sec' │ '± 2.81 %' │ '+ 40.17 %'             │
-│  'undici - pipeline'   │ 60      │ '5836.82 req/sec' │ '± 2.99 %' │ '+ 66.81 %'             │
-│  'undici - request'    │ 65      │ '6831.25 req/sec' │ '± 2.83 %' │ '+ 95.23 %'             │
-│  'undici - stream'     │ 55      │ '6874.30 req/sec' │ '± 2.91 %' │ '+ 96.46 %'             │
-│  'undici - dispatch'   │ 55      │ '7791.23 req/sec' │ '± 2.96 %' │ '+ 122.67 %'            │
-└────────────────────────┴─────────┴───────────────────┴────────────┴─────────────────────────┘
-```
-
 ## Undici vs. Fetch
 
 ### Overview
@@ -239,9 +200,7 @@ await fetch('https://example.com', {
 ```
 
 `install()` replaces the global `fetch`, `Headers`, `Response`, `Request`, and
-`FormData` implementations with undici's versions, so they all match. It also
-installs undici's `WebSocket`, `CloseEvent`, `ErrorEvent`, `MessageEvent`, and
-`EventSource` globals.
+`FormData` implementations with undici's versions, so they all match.
 
 Avoid mixing a global `FormData` with `undici.fetch()`, or `undici.FormData`
 with the built-in global `fetch()`.
@@ -324,12 +283,12 @@ const data2 = await getData();
 
 ## Global Installation
 
-Undici provides an `install()` function to add fetch-related and other web API classes to `globalThis`, making them available globally:
+Undici provides an `install()` function to add all WHATWG fetch classes to `globalThis`, making them available globally:
 
 ```js
 import { install } from 'undici'
 
-// Install undici's global web APIs
+// Install all WHATWG fetch classes globally
 install()
 
 // Now you can use fetch classes globally without importing
@@ -357,9 +316,8 @@ The `install()` function adds the following classes to `globalThis`:
 
 When you call `install()`, these globals come from the same undici
 implementation. For example, global `fetch` and global `FormData` will both be
-undici's versions, and `WebSocket` and `EventSource` will also come from
-undici, which is the recommended setup if you want to use undici through
-globals.
+undici's versions, which is the recommended setup if you want to use undici
+through globals.
 
 This is useful for:
 - Polyfilling environments that don't have fetch
@@ -379,18 +337,6 @@ The `body` mixins are the most common way to format the request/response body. M
 > [!NOTE]
 > The body returned from `undici.request` does not implement `.formData()`.
 
-> [!WARNING]
-> The body mixins `.arrayBuffer()`, `.blob()`, `.bytes()`, `.json()`, `.text()`,
-> and `.formData()` buffer the entire body in memory before returning. Where
-> applicable, they also decode or parse the payload and retain that
-> representation in memory. Calling these methods therefore means trusting that
-> the response body is small enough to fit in the available memory. Do not use
-> them for responses from untrusted or user-controlled sources. Instead, consume
-> the response body as a stream and enforce an application-specific size limit:
-> use `response.body` for fetch responses or the `body` returned by
-> `undici.request()`. For streaming decoded text, use `body.textStream()` on a
-> fetch `Request` or `Response`.
-
 Example usage:
 
 ```js
@@ -419,64 +365,71 @@ For more information about their behavior, please reference the body mixin from
 
 This section documents our most commonly used API methods. Additional APIs are documented in their own files within the [docs](./docs/) folder and are accessible via the navigation list on the left side of the docs site.
 
-For the top-level APIs below, the `url` argument supplies the request origin and
-path. Do not pass `origin` or `path` in the second `options` argument. The linked
-`Dispatcher` option types include those fields because dispatcher methods are
-lower-level APIs that do not receive a separate `url` argument.
+### `undici.request([url, options]): Promise`
+
+Arguments:
 
-### `undici.request([url, options])`
+* **url** `string | URL | UrlObject`
+* **options** [`RequestOptions`](./docs/docs/api/Dispatcher.md#parameter-requestoptions)
+  * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)
+  * **method** `String` - Default: `PUT` if `options.body`, otherwise `GET`
 
-* `url` {string|URL|UrlObject}
-* `options` {RequestOptions} See [`RequestOptions`](./docs/docs/api/Dispatcher.md#parameter-requestoptions).
-  * `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
-  * `method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.
-* Returns: {Promise} A promise with the result of the `Dispatcher.request` method.
+Returns a promise with the result of the `Dispatcher.request` method.
 
 Calls `options.dispatcher.request(options)`.
 
 See [Dispatcher.request](./docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback) for more details, and [request examples](./docs/examples/README.md) for examples.
 
-### `undici.stream([url, options, ]factory)`
+### `undici.stream([url, options, ]factory): Promise`
 
-* `url` {string|URL|UrlObject}
-* `options` {StreamOptions} See [`StreamOptions`](./docs/docs/api/Dispatcher.md#parameter-streamoptions).
-  * `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
-  * `method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.
-* `factory` {Function} `Dispatcher.stream.factory`.
-* Returns: {Promise} A promise with the result of the `Dispatcher.stream` method.
+Arguments:
+
+* **url** `string | URL | UrlObject`
+* **options** [`StreamOptions`](./docs/docs/api/Dispatcher.md#parameter-streamoptions)
+  * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)
+  * **method** `String` - Default: `PUT` if `options.body`, otherwise `GET`
+* **factory** `Dispatcher.stream.factory`
+
+Returns a promise with the result of the `Dispatcher.stream` method.
 
 Calls `options.dispatcher.stream(options, factory)`.
 
 See [Dispatcher.stream](./docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback) for more details.
 
-### `undici.pipeline([url, options, ]handler)`
+### `undici.pipeline([url, options, ]handler): Duplex`
+
+Arguments:
 
-* `url` {string|URL|UrlObject}
-* `options` {PipelineOptions} See [`PipelineOptions`](./docs/docs/api/Dispatcher.md#parameter-pipelineoptions).
-  * `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
-  * `method` {string} **Default:** `PUT` if `options.body`, otherwise `GET`.
-* `handler` {Function} `Dispatcher.pipeline.handler`.
-* Returns: {Duplex} A `stream.Duplex`.
+* **url** `string | URL | UrlObject`
+* **options** [`PipelineOptions`](./docs/docs/api/Dispatcher.md#parameter-pipelineoptions)
+  * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)
+  * **method** `String` - Default: `PUT` if `options.body`, otherwise `GET`
+* **handler** `Dispatcher.pipeline.handler`
+
+Returns: `stream.Duplex`
 
 Calls `options.dispatch.pipeline(options, handler)`.
 
 See [Dispatcher.pipeline](./docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler) for more details.
 
-### `undici.connect([url, options])`
+### `undici.connect([url, options]): Promise`
 
 Starts two-way communications with the requested resource using [HTTP CONNECT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT).
 
-* `url` {string|URL|UrlObject}
-* `options` {ConnectOptions} See [`ConnectOptions`](./docs/docs/api/Dispatcher.md#parameter-connectoptions).
-  * `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
-* `callback` {Function} (optional) — `(err, data) => void`.
-* Returns: {Promise} A promise with the result of the `Dispatcher.connect` method.
+Arguments:
+
+* **url** `string | URL | UrlObject`
+* **options** [`ConnectOptions`](./docs/docs/api/Dispatcher.md#parameter-connectoptions)
+  * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)
+* **callback** `(err: Error | null, data: ConnectData | null) => void` (optional)
+
+Returns a promise with the result of the `Dispatcher.connect` method.
 
 Calls `options.dispatch.connect(options)`.
 
 See [Dispatcher.connect](./docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback) for more details.
 
-### `undici.fetch(input[, init])`
+### `undici.fetch(input[, init]): Promise`
 
 Implements [fetch](https://fetch.spec.whatwg.org/#fetch-method).
 
@@ -642,15 +595,18 @@ The [Fetch Standard](https://fetch.spec.whatwg.org) requires implementations to
 
 Undici limits the number of `Content-Encoding` layers in a response to **5** to prevent resource exhaustion attacks. If a server responds with more than 5 content-encodings (e.g., `Content-Encoding: gzip, gzip, gzip, gzip, gzip, gzip`), the fetch will be rejected with an error. This limit matches the approach taken by [curl](https://curl.se/docs/CVE-2022-32206.html) and [urllib3](https://github.com/advisories/GHSA-gm62-xv2j-4rw9).
 
-#### `undici.upgrade([url, options])`
+#### `undici.upgrade([url, options]): Promise`
 
 Upgrade to a different protocol. See [MDN - HTTP - Protocol upgrade mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism) for more details.
 
-* `url` {string|URL|UrlObject}
-* `options` {UpgradeOptions} See [`UpgradeOptions`](./docs/docs/api/Dispatcher.md#parameter-upgradeoptions).
-  * `dispatcher` {Dispatcher} **Default:** [getGlobalDispatcher](#undicigetglobaldispatcher).
-* `callback` {Function} (optional) — `(error, data) => void`.
-* Returns: {Promise} A promise with the result of the `Dispatcher.upgrade` method.
+Arguments:
+
+* **url** `string | URL | UrlObject`
+* **options** [`UpgradeOptions`](./docs/docs/api/Dispatcher.md#parameter-upgradeoptions)
+  * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)
+* **callback** `(error: Error | null, data: UpgradeData) => void` (optional)
+
+Returns a promise with the result of the `Dispatcher.upgrade` method.
 
 Calls `options.dispatcher.upgrade(options)`.
 
@@ -658,26 +614,20 @@ See [Dispatcher.upgrade](./docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-
 
 ### `undici.setGlobalDispatcher(dispatcher)`
 
-* `dispatcher` {Dispatcher}
+* dispatcher `Dispatcher`
 
 Sets the global dispatcher used by Common API Methods. Global dispatcher is shared among compatible undici modules,
 including undici that is bundled internally with node.js.
 
-Undici stores this dispatcher under `Symbol.for('undici.globalDispatcher.2')`.
-
-`setGlobalDispatcher()` also mirrors the configured dispatcher to
-`Symbol.for('undici.globalDispatcher.1')` using `Dispatcher1Wrapper`, so Node.js built-in `fetch`
-can keep using the legacy handler contract while Undici uses the new handler API.
-
 ### `undici.getGlobalDispatcher()`
 
 Gets the global dispatcher used by Common API Methods.
 
-* Returns: {Dispatcher}
+Returns: `Dispatcher`
 
 ### `undici.setGlobalOrigin(origin)`
 
-* `origin` {string|URL|undefined}
+* origin `string | URL | undefined`
 
 Sets the global origin used in `fetch`.
 
@@ -695,17 +645,17 @@ console.log(response.url) // http://localhost:3000/api/ping
 
 Gets the global origin used in `fetch`.
 
-* Returns: {URL}
+Returns: `URL`
 
 ### `UrlObject`
 
-* `port` {string|number} (optional)
-* `path` {string} (optional)
-* `pathname` {string} (optional)
-* `hostname` {string} (optional)
-* `origin` {string} (optional)
-* `protocol` {string} (optional)
-* `search` {string} (optional)
+* **port** `string | number` (optional)
+* **path** `string` (optional)
+* **pathname** `string` (optional)
+* **hostname** `string` (optional)
+* **origin** `string` (optional)
+* **protocol** `string` (optional)
+* **search** `string` (optional)
 
 #### Expect
 
@@ -718,9 +668,8 @@ Refs: https://tools.ietf.org/html/rfc7231#section-5.1.1
 #### Pipelining
 
 Undici will only use pipelining if configured with a `pipelining` factor
-greater than `1`. Only enable pipelining when the remote server is trusted.
-Also it is important to pass `blocking: false` to the request options to
-properly pipeline requests.
+greater than `1`. Also it is important to pass `blocking: false` to the
+request options to properly pipeline requests.
 
 Undici always assumes that connections are persistent and will immediately
 pipeline requests, without checking whether the connection is persistent.
@@ -782,11 +731,10 @@ and `undici.Agent`) which will enable the family autoselection algorithm when es
 Undici aligns with the Node.js LTS schedule. The following table shows the supported versions:
 
 | Undici Version | Bundled in Node.js | Node.js Versions Supported | End of Life |
-|----------------|--------------------|----------------------------|-------------|
-| 5.x            | 18.x               | ≥14.0 (tested: 14, 16, 18) | 2024-04-30  |
-| 6.x            | 20.x, 22.x         | ≥18.17 (tested: 18, 20, 21, 22) | 2027-04-30  |
-| 7.x            | 24.x               | ≥20.18.1 (tested: 20, 22, 24) | 2028-04-30  |
-| 8.x            | 26.x               | ≥22.19.0 (tested: 22, 24, 26) | 2029-04-30  |
+|----------------|-------------------|----------------------------|-------------|
+| 5.x           | 18.x              | ≥14.0 (tested: 14, 16, 18) | 2024-04-30  |
+| 6.x           | 20.x, 22.x       | ≥18.17 (tested: 18, 20, 21, 22) | 2026-04-30  |
+| 7.x           | 24.x              | ≥20.18.1 (tested: 20, 22, 24) | 2027-04-30  |
 
 ## License