@opencoredev/sandbox-sdk 0.2.0 → 1.0.0-beta.0

package/dist/providers/upstash/index.js

@@ -0,0 +1,111 @@
+import{s,t}from"../../chunk-t5vr9nd8.js";import{d}from"../../chunk-exv1kf89.js";import{o}from"../../chunk-yed8mvs7.js";import{e,l}from"../../chunk-gc8zdxyb.js";import{posix as Q}from"node:path";var oe=`import os,select,_signal as signal,sys,time,fcntl
+${d}
+command,directory,cwd,limit,activity=sys.argv[1:]
+if activity:
+ os.makedirs(os.path.dirname(activity),exist_ok=True)
+ os.mkdir(activity,mode=0o700)
+os.makedirs(directory,mode=0o700,exist_ok=True)
+cancel=directory+"/cancel"
+with open(directory+"/lock","w") as lock:
+ fcntl.flock(lock,fcntl.LOCK_EX)
+ if os.path.exists(cancel):
+  print("R:0:1:1")
+  sys.exit(0)
+ try:
+  with stdin_file() as f: p=Process(dict(command=command,cwd=cwd),dict(os.environ,PWD=cwd),f,True)
+ except OSError as error:
+  print("E:"+str(error).encode().hex())
+  print("R:2:0:0")
+  os.unlink(directory+"/lock"); os.rmdir(directory)
+  sys.exit(0)
+ with open(directory+"/pid","w") as f: f.write(str(p.pid))
+streams={p.stdout.fileno():"O",p.stderr.fileno():"E"}
+deadline=time.monotonic()+float(limit)
+timedout=False
+size=0
+spill=None
+try:
+ while streams or p.poll() is None:
+  if not timedout and (time.monotonic()>=deadline or os.path.exists(cancel)):
+   timedout=True
+   try: os.killpg(p.pid,signal.SIGKILL)
+   except ProcessLookupError: pass
+  for fd in select.select(list(streams),[],[],0.02)[0]:
+   data=os.read(fd,4096)
+   if not data: del streams[fd]; continue
+   frame=streams[fd]+":"+data.hex()+"\\n"
+   size+=len(frame)
+   if size>65536:
+    if spill is None: spill=open(directory+"/output","w")
+    spill.write(frame)
+   else: sys.stdout.write(frame)
+ code=p.wait()
+ print("R:%d:%d:%d"%(code if code>=0 else 128-code,timedout,spill is not None))
+except BaseException:
+ try: os.killpg(p.pid,signal.SIGKILL)
+ except ProcessLookupError: pass
+ p.wait()
+ raise
+finally:
+ if activity:
+  try: os.rmdir(activity)
+  except FileNotFoundError: pass
+ if spill is not None: spill.close()
+ else:
+  for name in ('pid','lock','cancel'):
+   try: os.unlink(directory+'/'+name)
+   except FileNotFoundError: pass
+  os.rmdir(directory)
+`,re=`import os,signal,sys,fcntl,time
+p=sys.argv[1]
+pid=None
+for attempt in range(3):
+ try:
+  os.makedirs(p,mode=0o700,exist_ok=True)
+  with open(p+"/lock","w") as lock:
+   fcntl.flock(lock,fcntl.LOCK_EX)
+   open(p+"/cancel","w").close()
+   try:
+    with open(p+"/pid") as f: pid=int(f.read())
+    os.killpg(pid,signal.SIGKILL)
+   except (FileNotFoundError,ProcessLookupError): pass
+  break
+ except FileNotFoundError:
+  if attempt==2: raise
+if pid:
+ end=time.monotonic()+2
+ while True:
+  try: os.killpg(pid,0)
+  except ProcessLookupError: break
+  if time.monotonic()>=end: sys.exit(1)
+  time.sleep(.01)
+`;async function H(n,i,x){if(i.signal?.aborted)return{exitCode:null,timedOut:!0};let g=`/tmp/.sandbox-sdk/exec/sdk-${crypto.randomUUID()}`,c=Object.entries(s).filter(([r])=>(r in i.env)).map(([r,a])=>t(`${r}=${a}`)).join(" "),f=`${x?`${x} && `:""}env ${c} python3 -S -u -c ${t(oe)} ${t(i.command)} ${t(g)} ${t(i.cwd)} ${t(String(i.timeoutMs/1000))} ''`;if(Buffer.byteLength(f)>=98304)return;let w=Date.now()+i.timeoutMs,B=!1,_=!1,b=!1,I=()=>{},C=new Promise((r)=>{I=()=>r(void 0)}),T,S,y=()=>new e("Command output is incomplete. Upstash did not confirm exact output and exit. Inspect the box before retrying.",{code:"outcome_unknown",provider:"upstash",sandboxId:n.id}),k=()=>{if(B=!0,I(),_)return;T??=n.exec.command(`python3 -c ${t(re)} ${t(g)}`).then((r)=>{if(r.exitCode!==0)throw y()}).catch((r)=>{S=r})},A={stdout:new TextDecoder("utf-8",{ignoreBOM:!0}),stderr:new TextDecoder("utf-8",{ignoreBOM:!0})},E=(r)=>{let a=/^(O|E):([0-9a-f]*)$/.exec(r);if(!a||r.length>8194||Buffer.from(a[2]??"","hex").toString("hex")!==a[2])throw y();let u=a[1]==="O"?"stdout":"stderr",h=A[u].decode(Buffer.from(a[2]??"","hex"),{stream:!0});if(h)i.onChunk({stream:u,text:h})};i.signal?.addEventListener("abort",k,{once:!0});let O=setTimeout(k,Math.max(0,w-Date.now()));try{let r=await n.exec.command(f);if(r.exitCode===127&&r.stderr.includes("python3")&&!B)return;let a=r.stdout.trimEnd().split(`
+`),u=/^R:(\d+):([01]):([01])$/.exec(a.pop()??"");if(r.exitCode!==0||!u)throw y();_=!0,b=u[3]==="1";for(let p of a)if(p)E(p);if(b&&!B){let p=0,m="";while(!B){let v=await Promise.race([n.files.read(`${g}/output`,{offset:p,length:65536,encoding:"base64"}),C]);if(v===void 0)break;let U=Buffer.from(v,"base64");if(B)break;p+=U.length,m+=U.toString("ascii");let P;while((P=m.indexOf(`
+`))>=0)E(m.slice(0,P)),m=m.slice(P+1);if(m.length>8194)throw y();if(U.length<65536){if(m)throw y();break}}}for(let p of["stdout","stderr"]){let m=A[p].decode();if(m)i.onChunk({stream:p,text:m})}if(await T,S!==void 0)throw y();let h=u[2]==="1"||B;return{exitCode:h?null:Number(u[1]),timedOut:h}}catch(r){if(!_){if(k(),await T,S!==void 0)throw y()}throw r}finally{if(clearTimeout(O),i.signal?.removeEventListener("abort",k),await T,_&&(T||b))await n.files.remove(g,{recursive:!0}).catch(()=>{})}}function X(n,i,x=0){let g=n instanceof Error?`${n.name}: ${n.message}`:"Native request failed",c=i(g).replace(/https?:\/\/[^\s"'<>]+/gi,"[URL REDACTED]").replace(/(\bauthorization["']?\s*[:=]\s*)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\r\n;]+)/gi,"$1[REDACTED]").replace(/\bBearer\s+[^\s"',;]+/gi,"Bearer [REDACTED]").replace(/((?:["']?(?:authorization|api[-_]?key|token|password|secret)["']?)\s*[:=]\s*)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;]+)/gi,"$1[REDACTED]").replace(/\p{Cc}+/gu," ").slice(0,1000);return n instanceof Error&&n.cause!==void 0&&x<2?`${c}; caused by ${X(n.cause,i,x+1)}`:c}function D(n,i,x=!1,g=x?"files":"request",c=(f)=>{let w=new l;return w.add([process.env.UPSTASH_BOX_API_KEY??""]),w.text(f)}){if(n instanceof e)return n;let f=n&&typeof n==="object"&&"statusCode"in n?n.statusCode:void 0,w="provider";if(f===401||f===403)w="auth";else if(f===404)w=x?"file_not_found":"not_found";else if(f===410)w="not_found";else if(f===429||f===402)w="quota";else if(f===408||f===504)w="timeout";else if(typeof f==="number"&&f>=500)w="unavailable";else if(f===400||f===422)w="invalid_argument";let B=`${g}${typeof f==="number"?` HTTP ${f}`:""}: ${X(n,c)}`;return new e(`Upstash Box ${g} failed (${w}${typeof f==="number"?`, HTTP ${f}`:""}). The provider could not complete the operation. Check credentials, limits, and sandbox state.`,{code:w,provider:"upstash",sandboxId:i,retryable:["quota","timeout","unavailable"].includes(w),cause:B})}function z(n){throw new e(`${n}. Upstash Box cannot enforce this request. Choose supported settings.`,{code:"unsupported",provider:"upstash"})}import{StringDecoder as Z}from"node:string_decoder";async function G(n,i,x,g){if(i.signal?.aborted)return{exitCode:null,timedOut:!0};let c,f=!1,w=()=>{f=!0,c?.kill("KILL")},B=setTimeout(w,i.timeoutMs);i.signal?.addEventListener("abort",w,{once:!0});let _=`sdk-prepared-${crypto.randomUUID()}
+`,b="",I=x!==void 0,C=new Z("utf8"),T=new Z("utf8");try{if(c=await n.exec.session({argv:x?["sh","-c",`${x} && printf '%s
+' '${_.trimEnd()}' && cd "$1" && exec sh -c "$2"`,"sh",i.cwd,i.command]:["sh","-c",i.command],cwd:x?"/":i.cwd,env:Object.entries(i.env).map(([A,E])=>`${A}=${E}`),onStdout:(A)=>{let E=C.write(Buffer.from(A));if(I){b+=E;let O=b.indexOf(_);if(O>=0)E=b.slice(0,O)+b.slice(O+_.length),b="",I=!1,g?.();else{let r=Math.max(0,b.length-_.length+1);E=b.slice(0,r),b=b.slice(r)}}if(E)i.onChunk({stream:"stdout",text:E})},onStderr:(A)=>{let E=T.write(Buffer.from(A));if(E)i.onChunk({stream:"stderr",text:E})}}),f||i.signal?.aborted)w();else{if(i.stdin!==void 0)c.write(i.stdin);c.endStdin()}let S=await c.wait();if(S<0&&!f)throw new e("Command session disconnected. Upstash could not confirm an exit code. Inspect the box before retrying.",{code:"unavailable",provider:"upstash",sandboxId:n.id});let y=b+C.end();if(y)i.onChunk({stream:"stdout",text:y});let k=T.end();if(k)i.onChunk({stream:"stderr",text:k});return{exitCode:f?null:S,timedOut:f}}catch(S){throw c?.close(),S}finally{clearTimeout(B),i.signal?.removeEventListener("abort",w),c?.close()}}async function J(n,i,x,g){let c=(y)=>`'${y.replaceAll("'","'\\''")}'`,f=`/tmp/.sandbox-sdk/upstash-runs/${crypto.randomUUID()}`,w=`${f}/env`,B=`${g?`${g} && `:""}chmod 600 ${c(w)} && . ${c(w)} && /bin/rm -f -- ${c(w)} || exit 1; echo $$ > ${c(`${f}/pid`)}; cd ${c(i.cwd)} || exit 1; sh -c ${c(i.command)}; code=$?; printf '%s' "$code" > ${c(`${f}/exit`)}; exit "$code"`,_;try{if((await n.exec.command(`umask 077; mkdir -p /tmp/.sandbox-sdk/upstash-runs && mkdir ${c(f)} && : > ${c(w)}`)).exitCode!==0)throw Error("Durable process environment setup failed");if(await n.files.write({path:w,content:Object.entries(i.env).map(([A,E])=>`export ${c(`${A}=${E}`)}`).join(`
+`)+`
+`}),(await n.exec.command(`nohup setsid sh -c ${c(B)} > /dev/null 2>&1 < /dev/null &`)).exitCode!==0)throw Error("Durable process launch failed");for(let A=0;A<200;A++){try{let E=Number(await n.files.read(`${f}/pid`));if(Number.isSafeInteger(E)&&E>1){_=E;break}}catch(E){if(D(E,n.id,!0).code!=="file_not_found")throw E}await new Promise((E)=>setTimeout(E,25))}if(_===void 0)throw Error("Durable process PID missing")}catch(y){throw await n.files.remove(w).catch(()=>{}),await x(f),y}let b=_,I=!1,C=(async()=>{while(!0){if(I)await new Promise(()=>{});try{let y=Number(await n.files.read(`${f}/exit`));if(!Number.isInteger(y)||y<0||y>255)throw Error("Invalid durable exit code");return{exitCode:y,signal:null}}catch(y){let k=D(y,n.id,!0).code;if(k!=="file_not_found"&&k!=="unavailable"&&k!=="quota"&&k!=="timeout")throw y}await new Promise((y)=>setTimeout(y,50))}})();C.catch(()=>{});let T=async(y)=>{if((await n.exec.command(`kill -${y} -${b} 2>/dev/null || ! kill -0 -${b} 2>/dev/null`)).exitCode!==0)throw new e("Process termination is unconfirmed. The remote process group could not be signalled. Destroy the box before retrying.",{code:"outcome_unknown",provider:"upstash",sandboxId:n.id})},S=!1;return{pid:b,wait:()=>C,detach(){I=!0},async stop({graceMs:y}){if(S)return;await T("TERM"),await new Promise((k)=>setTimeout(k,y)),await T("KILL");try{await n.files.read(`${f}/exit`)}catch(k){if(D(k,n.id,!0).code!=="file_not_found")throw k;await n.files.write({path:`${f}/exit`,content:"137"})}await C,S=!0}}}import{posix as ne}from"node:path";var j=4194304,L=(n)=>`'${n.replaceAll("'","'\\''")}'`;async function K(n,i,x){if(!x)try{return new Uint8Array(Buffer.from(await n.files.read(i,{encoding:"base64"}),"base64"))}catch(w){if(["auth","file_not_found","not_found","quota"].includes(D(w,n.id,!0).code))throw w}let g=[],c=x?.offset??0,f=x?.length??1/0;while(f>0){let w=Math.min(j,f),B=Buffer.from(await n.files.read(i,{offset:c,length:w,encoding:"base64"}),"base64");if(g.push(B),c+=B.length,f-=B.length,B.length<w)break}return new Uint8Array(Buffer.concat(g))}async function Y(n,i,x,g){if(g){let b=await n.exec.session({argv:["sh","-c",`${g} && exec python3 -c "$1" "$2"`,"sh","import os,sys; p=sys.argv[1]; os.makedirs(os.path.dirname(p),exist_ok=True); f=open(p,'wb'); f.write(sys.stdin.buffer.read()); f.close()",i],cwd:"/"});try{if(b.write(x),b.endStdin(),await b.wait()!==0)throw new e("File write failed. Check workspace permissions and Python availability.",{code:"provider",provider:"upstash",sandboxId:n.id});return}finally{b.close()}}let c=async(_,b)=>{let I={path:_,content:Buffer.from(b).toString("base64"),encoding:"base64"};try{await n.files.write(I)}catch(C){if(D(C,n.id,!0).code!=="file_not_found")throw C;await n.files.mkdir(ne.dirname(_),{parents:!0}),await n.files.write(I)}};if(x.length<=j)return c(i,x);let f=`/tmp/.sandbox-sdk/upload-${crypto.randomUUID()}`;if((await n.exec.command(`umask 077; mkdir -p /tmp/.sandbox-sdk && mkdir ${L(f)}`)).exitCode!==0)throw new e("Private upload staging could not be created. Check guest permissions.",{code:"provider",provider:"upstash",sandboxId:n.id});let B=!1;try{let _=0;for(let C=0;C<x.length;C+=j)await c(`${f}/${_++}`,x.subarray(C,C+j));let b=`import os,sys,shutil,tempfile,stat
+p,d,n=sys.argv[1:]; p=os.path.realpath(p); tmp=None
+try:
+ os.makedirs(os.path.dirname(p),exist_ok=True)
+ mode=stat.S_IMODE(os.stat(p).st_mode) if os.path.exists(p) else 0o644
+ with tempfile.NamedTemporaryFile(dir=os.path.dirname(p),prefix='.sandbox-upload-',delete=False) as out:
+  tmp=out.name; os.fchmod(out.fileno(),mode)
+  for i in range(int(n)):
+   with open(d+'/'+str(i),'rb') as part: shutil.copyfileobj(part,out)
+  out.flush(); os.fsync(out.fileno())
+ os.replace(tmp,p); tmp=None
+finally:
+ if tmp is not None: os.unlink(tmp)
+ shutil.rmtree(d,ignore_errors=True)`;B=!0;let I;try{I=await n.exec.command(`python3 -c ${L(b)} ${L(i)} ${L(f)} ${_}`)}catch{throw new e(`Large upload outcome is unknown. Inspect ${f} and the destination before retrying; destroy the sandbox to remove any retained staging.`,{code:"outcome_unknown",provider:"upstash",sandboxId:n.id})}if(I.exitCode!==0)throw await n.files.remove(f,{recursive:!0}).catch(()=>{}),new e("Large file assembly failed. Check guest Python and destination permissions.",{code:"provider",provider:"upstash",sandboxId:n.id})}finally{if(!B)await n.files.remove(f,{recursive:!0})}}var ie=`import os,sys,json,stat
+p=sys.argv[1]
+try: names=os.listdir(p)
+except (FileNotFoundError,NotADirectoryError): names=[]
+out=[]
+for n in names:
+ try: s=os.lstat(os.path.join(p,n))
+ except FileNotFoundError: print('SDK_FILE_NOT_FOUND'); sys.exit(0)
+ m=s.st_mode
+ out.append([n.encode('utf-8','surrogateescape').decode('utf-8','replace'),'symlink' if stat.S_ISLNK(m) else 'directory' if stat.S_ISDIR(m) else 'file' if stat.S_ISREG(m) else 'other',s.st_size,s.st_mtime_ns//1000000])
+print(json.dumps(out))`;function ae(n){if(!Array.isArray(n))return;let i=[];for(let x of n){if(!Array.isArray(x)||x.length!==4)return;let[g,c,f,w]=x;if(typeof g!=="string"||c!=="file"&&c!=="directory"&&c!=="symlink"&&c!=="other"||typeof f!=="number"||typeof w!=="number")return;i.push({name:g,type:c,size:f,modifiedAt:w})}return i}async function W(n,i,x){if(!i.startsWith("/"))return;let g=await n.exec.command(`${x?`${x} && `:""}python3 -c ${L(ie)} ${L(i)}`);if(g.exitCode!==0)return;let c=g.stdout.trim();if(c==="SDK_FILE_NOT_FOUND")throw Object.assign(Error("Directory entry vanished during listing"),{statusCode:404});try{return ae(JSON.parse(c))}catch{return}}var V=259200,F="sandbox-sdk",M="SANDBOX_SDK_UPSTASH_METADATA",N='if ! mkdir -p /workspace 2>/dev/null || [ ! -w /workspace ]; then sudo -n install -d -o "$(id -u)" -g "$(id -g)" -m 755 /workspace; fi && test -w /workspace',de="/tmp/.sandbox-sdk/upstash.json",q='for d in /tmp/.sandbox-sdk/procs/*; do [ -f "$d/spec.json" ] && [ ! -f "$d/exit" ] && printf 137 > "$d/exit"; done; rm -rf /tmp/.sandbox-sdk/upstash-runs; true';function ce(n){let i;try{i=JSON.parse(n)}catch{throw new e("Invalid SDK metadata",{code:"not_found",provider:"upstash"})}if(!i||typeof i!=="object"||!("version"in i)||i.version!==1||!("labels"in i)||!i.labels||typeof i.labels!=="object"||Array.isArray(i.labels)||"key"in i&&typeof i.key!=="string")throw new e("Invalid SDK metadata",{code:"not_found",provider:"upstash"});let x={};for(let[g,c]of Object.entries(i.labels)){if(typeof c!=="string")throw new e("Invalid SDK label",{code:"not_found",provider:"upstash"});Object.defineProperty(x,g,{value:c,enumerable:!0,writable:!0,configurable:!0})}return{version:1,labels:x,..."key"in i&&typeof i.key==="string"?{key:i.key}:{}}}function ee(n,i){return{id:n.id,key:i.key,labels:i.labels,createdAt:n.created_at*1000,state:n.status==="paused"?"paused":n.status==="running"||n.status==="idle"?"running":"stopped"}}var R=(n)=>("ephemeral"in n)&&n.ephemeral===!0;function te(n,i){if(i.type==="other")z("Special filesystem entries are not supported");return{path:n,type:i.type,size:i.size,modifiedAt:Date.parse(i.mod_time)}}function le(n){if(typeof n!=="object")return{mode:n==="none"?"deny-all":"allow-all"};if(!n.allow.length)return{mode:"deny-all"};if(n.allow.some((i)=>i.length>253||!/^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(i)))z("Network allow entries must be DNS hostnames");return{mode:"custom",allowedDomains:n.allow}}function Ae(n={}){let i=n.ephemeral?n.ttlSeconds??3600:void 0;if(i!==void 0&&(!Number.isSafeInteger(i)||i<1||i>V))throw new e(`Ephemeral ttlSeconds must be a whole number from 1 to ${V}.`,{code:"invalid_argument",provider:"upstash"});let x=new l,g=new Map,c=new Set,f=new Map,w=new Map,B,_=new Map,b=new Map,I=(r)=>{for(let a of _.get(r)??[])a();_.delete(r)},C=()=>{let r=n.apiKey??process.env.UPSTASH_BOX_API_KEY;if(!r)throw new e("Upstash Box API key is missing. Authentication is required. Set UPSTASH_BOX_API_KEY or pass apiKey.",{code:"auth",provider:"upstash"});return x.add([r]),{apiKey:r,baseUrl:n.baseUrl,enableTelemetry:n.enableTelemetry}},T=async()=>{let r=C(),{Box:a,EphemeralBox:u}=await(B??=o("@upstash/box","upstash",()=>import("@upstash/box")));return{Box:a,EphemeralBox:u,config:r}};async function S(r,a,u=!1,h="request"){try{return await r()}catch(p){throw D(p,a,u,h,(m)=>x.text(m))}}async function y(r){let a=f.get(r);if(a){let v=a();return g.set(r,v),f.delete(r),v}let u=g.get(r);if(u)return u;let{Box:h,config:p}=await T(),m=await h.get(r,{...p,timeout:n.requestTimeoutMs});return g.set(r,m),c.add(r),m}let k=(r,a,u)=>S(async()=>u(await y(r)),r,!0,`files.${a}`),A=async(r)=>{let a=await r.exec.command(`if [ -n "$${M}" ]; then printf %s "$${M}"; else cat ${t(de)}; fi`);if(a.exitCode!==0)throw new e("SDK metadata was not found",{code:"not_found",provider:"upstash",sandboxId:r.id});return ce(a.stdout)};async function E(r){let a=C(),u=(a.baseUrl??process.env.UPSTASH_BOX_BASE_URL??"https://us-east-1.box.upstash.com").replace(/\/$/,""),h=await fetch(`${u}/v2/box/snapshots`,{headers:{Authorization:`Bearer ${a.apiKey}`},signal:AbortSignal.timeout(n.requestTimeoutMs??30000)});if(!h.ok)throw Object.assign(Error("Snapshot metadata lookup failed"),{statusCode:h.status});let p=await h.json();if(!p||typeof p!=="object"||!("snapshots"in p)||p.snapshots!==null&&!Array.isArray(p.snapshots))throw new e("Invalid snapshot metadata response. Upstash did not return a snapshot list. Retry when the service is available.",{code:"provider",provider:"upstash"});for(let m of p.snapshots??[]){let v=m;if(!v||typeof v!=="object"||!("id"in v)||v.id!==r)continue;if("name"in v&&typeof v.name==="string"){let U=/^sdk-v1-(small|medium|large)-/.exec(v.name)?.[1];if(U==="small"||U==="medium"||U==="large")return U}if("box_id"in v&&typeof v.box_id==="string")try{return(await y(v.box_id)).size}catch(U){if(D(U).code!=="not_found")throw U}z("Snapshot size is unknown because its source box is unavailable; pass an explicit size")}throw new e("Snapshot was not found. It may have been deleted. Check the snapshot ID and account.",{code:"not_found",provider:"upstash"})}let O={name:"upstash",keyMode:"best-effort",capabilities:new Set(i===void 0?["pause","snapshot","size","network-policy"]:["snapshot","size","network-policy"]),create:(r)=>S(async()=>{if(r.idleTimeoutMs!==void 0||r.timeoutMs!==void 0)z("Custom idle deadlines and hard lifetimes are not available on durable boxes");if(r.size!==void 0&&typeof r.size!=="string")z("Use small, medium, or large; exact CPU, memory, and disk sizes are unavailable");if(r.env&&M in r.env)throw new e(`${M} is reserved for SDK discovery metadata. Choose another environment variable name.`,{code:"invalid_argument",provider:"upstash"});x.add(Object.values(r.env??{}));let a=le(r.network),{Box:u,EphemeralBox:h,config:p}=await T(),m={version:1,key:r.key,labels:{...r.labels,"sandbox-sdk":"1"}},v={...p,runtime:n.runtime,size:r.size??(r.from===void 0?void 0:await E(r.from)),env:{...r.env,[M]:JSON.stringify(m)},labels:[F],networkPolicy:a,timeout:n.requestTimeoutMs},U=Date.now(),P=i===void 0?r.from===void 0?await u.create({...v,initCommand:q}):await u.fromSnapshot(r.from,{...v,initCommand:q}):r.from===void 0?await h.create({...v,ttl:i}):await h.fromSnapshot(r.from,{...v,ttl:i});try{if(r.signal?.aborted)throw new e("Creation aborted. The caller cancelled. Retry when ready.",{code:"aborted",provider:"upstash"});if(P instanceof u)g.set(P.id,P);else f.set(P.id,()=>new u({id:P.id,status:"running",created_at:U/1000,updated_at:U/1000,size:v.size??"small",labels:[F],network_policy:{mode:a.mode,..."allowedDomains"in a?{allowed_domains:a.allowedDomains}:{}}},{baseUrl:(p.baseUrl??process.env.UPSTASH_BOX_BASE_URL??"https://us-east-1.box.upstash.com").replace(/\/$/,""),headers:{"X-Box-Api-Key":p.apiKey},timeout:n.requestTimeoutMs??600000,debug:!1}));if(i!==void 0&&r.from!==void 0&&(await P.exec.command(q)).exitCode!==0)throw new e("Restored process records could not be invalidated",{code:"provider",provider:"upstash",sandboxId:P.id});return w.set(P.id,{...r.env,...s}),c.add(P.id),{id:P.id,key:m.key,labels:m.labels,createdAt:U,state:"running"}}catch(se){throw await P.delete(),g.delete(P.id),f.delete(P.id),c.delete(P.id),w.delete(P.id),se}},void 0,!1,"create"),list:(r)=>S(async()=>{let{Box:a,config:u}=await T(),h=[];for(let p of await a.list({...u,label:F})){if(!p.labels?.includes(F)||p.status==="deleted"||R(p)!==(i!==void 0))continue;try{let m=await A(await y(p.id));if(Object.entries(r).every(([v,U])=>m.labels[v]===U))h.push(ee(p,m))}catch(m){if(D(m).code!=="not_found")throw m}}return h},void 0,!1,"list"),async find(r){return(await O.list({})).find((a)=>a.key===r)},connect:(r)=>S(async()=>{let{Box:a,config:u}=await T(),h=(await a.list(u)).find((m)=>m.id===r);if(!h)throw Object.assign(Error("Missing box"),{statusCode:404});if(R(h)!==(i!==void 0))throw new e(`Box ${r} is ${R(h)?"an Ephemeral Box":"a durable Box"}. Connect with upstash({ ephemeral: ${R(h)} }).`,{code:"unsupported",provider:"upstash",sandboxId:r});let p=await y(r);return c.add(r),ee(h,await A(p))},r,!1,"connect"),destroy:(r)=>S(async()=>{try{await(await y(r)).delete()}catch(a){if(D(a).code!=="not_found")throw a}finally{I(r),b.delete(r),g.delete(r),w.delete(r),f.delete(r),c.delete(r)}},r,!1,"destroy"),exec:(r,a)=>S(async()=>{let u=await y(r),h=w.get(r)??s;if(a.streaming!==!0&&a.stdin===void 0&&a.timeoutMs+15000<=(n.requestTimeoutMs??600000)&&Object.entries(a.env).every(([m,v])=>h[m]===v)){let m=await H(u,a,c.has(r)?N:void 0);if(m){if(!m.timedOut)c.delete(r);return m}}return await G(u,a,c.has(r)?N:void 0,()=>c.delete(r))},r,!1,"exec"),startProcess:(r,a)=>S(async()=>{let u=await y(r),p=await J(u,a,i===void 0?()=>u.pause():(v)=>u.exec.command(`for p in $(pgrep -f ${t(`[${v[1]}]${v.slice(2)}/`)}); do kill -KILL -$p 2>/dev/null; done; true`),c.has(r)?N:void 0);c.delete(r);let m=_.get(r);if(!m)m=new Set,_.set(r,m);return m.add(p.detach),p.wait().finally(()=>m.delete(p.detach)).catch(()=>{}),{pid:p.pid,wait:()=>S(p.wait,r,!1,"process.wait"),stop:(v)=>S(()=>p.stop(v),r,!1,"process.stop")}},r,!1,"process.start"),async close(r){I(r),g.delete(r),w.delete(r),f.delete(r),c.delete(r)},files:{writeCreatesParents:!0,internal:[".step-git"],read:(r,a)=>k(r,"read",(u)=>K(u,a)),readRange:(r,a,u)=>k(r,"readRange",(h)=>K(h,a,u)),write:(r,a,u)=>k(r,"write",(h)=>Y(h,a,u,c.has(r)?N:void 0).then(()=>{c.delete(r)})),list:(r,a)=>k(r,"list",async(u)=>{let h=await W(u,a,c.has(r)?N:void 0);if(h)return c.delete(r),h.map((p)=>{if(p.type==="other")z("Special filesystem entries are not supported");return{path:Q.join(a,p.name),type:p.type,size:p.size,modifiedAt:p.modifiedAt}});return Promise.all((await u.files.list(a)).map(async(p)=>{let m=Q.join(a,p.name);return te(m,await u.files.stat(m))}))}),stat:(r,a)=>k(r,"stat",async(u)=>{try{return te(a,await u.files.stat(a))}catch(h){if(a!=="/workspace"||!c.has(r)||D(h,r,!0).code!=="file_not_found")throw h;return{path:a,type:"directory",size:0,modifiedAt:Date.now()}}}),remove:(r,a,u)=>k(r,"remove",async(h)=>{try{await h.files.remove(a,u)}catch(p){if(a!=="/workspace"||!c.has(r)||D(p,r,!0).code!=="file_not_found")throw p}if(a==="/workspace")c.delete(r)}),mkdir:(r,a)=>k(r,"mkdir",async(u)=>{if(!c.has(r))return u.files.mkdir(a,{parents:!0});if((await u.exec.command(`${N} && mkdir -p ${t(a)}`)).exitCode!==0)throw new e("Directory creation failed. Check guest permissions.",{code:"provider",provider:"upstash",sandboxId:r});c.delete(r)})},previewUrl:(r,a)=>{let u=b.get(r);if(!u)u=new Map,b.set(r,u);let h=u.get(a);if(h)return h;let p=S(async()=>{let m=await(await y(r)).getPublicURL(a,n.public?void 0:{bearerToken:!0});if(!n.public&&!m.token)throw Error("Protected preview returned no bearer token");return{url:m.url,...m.token?{headers:{Authorization:`Bearer ${m.token}`}}:{}}},r,!1,"preview");return u.set(a,p),p.catch(()=>u.delete(a)),p},...i===void 0?{pause:(r)=>S(async()=>{I(r),await(await y(r)).pause()},r,!1,"pause"),resume:(r)=>S(async()=>{await(await y(r)).resume()},r,!1,"resume")}:{},snapshot:(r)=>S(async()=>{let a=await y(r);return{id:(await a.snapshot({name:`sdk-v1-${a.size}-${crypto.randomUUID()}`})).id}},r,!1,"snapshot"),native(r){let a=f.get(r);if(a){let h=a();return g.set(r,h),f.delete(r),h}let u=g.get(r);if(!u)throw new e("Sandbox is not connected. No native object is cached. Connect first.",{code:"not_found",provider:"upstash",sandboxId:r});return u}};return O}export{Ae as upstash};

package/dist/providers/vercel/errors.d.ts

@@ -0,0 +1,3 @@
+import { SandboxError } from "../../errors.js";
+export declare function vercelError(error: unknown, sandboxId?: string): SandboxError;
+export declare function unsupported(message: string): never;

package/dist/providers/vercel/index.d.ts

@@ -0,0 +1,14 @@
+import type { Sandbox } from "@vercel/sandbox";
+import type { Provider } from "../../provider.js";
+import { type VercelOptions as NativeVercelOptions, type VercelCapability } from "./provider.js";
+export type { VercelCapability } from "./provider.js";
+export interface VercelOptions extends NativeVercelOptions {
+    /** Defaults to VERCEL_TOKEN; otherwise the native SDK uses VERCEL_OIDC_TOKEN. */
+    token?: string;
+    /** Defaults to VERCEL_TEAM_ID; required with token authentication. */
+    teamId?: string;
+    /** Defaults to VERCEL_PROJECT_ID; required with token authentication. */
+    projectId?: string;
+}
+export type VercelProvider = Provider<Sandbox, VercelCapability>;
+export declare function vercel(options?: VercelOptions): VercelProvider;

package/dist/providers/vercel/index.js

@@ -0,0 +1 @@
+import{t}from"../../chunk-t5vr9nd8.js";import{o}from"../../chunk-yed8mvs7.js";import{e}from"../../chunk-gc8zdxyb.js";import{createHash as q}from"node:crypto";import{posix as O}from"node:path";import{Readable as R}from"node:stream";function k(i,p){if(i instanceof e)return i;let l=typeof i==="object"&&i!==null&&"response"in i&&i.response instanceof Response?i.response.status:void 0,m=typeof i==="object"&&i!==null&&"code"in i?i.code:void 0,b=l===401||l===403?"auth":l===404?"not_found":l===429?"quota":l!==void 0&&l>=500?"unavailable":m==="ENOENT"?"file_not_found":m==="ENOTEMPTY"||m==="ENOTDIR"||l===400?"invalid_argument":i instanceof Error&&i.name==="AbortError"?"aborted":i instanceof Error&&i.name==="TimeoutError"?"timeout":i instanceof Error&&/credentials|OIDC|token/i.test(i.message)?"auth":"provider";return new e(`Vercel request failed (${b}). The provider could not complete the operation. Check credentials, resource limits, and the sandbox state before retrying.`,{code:b,provider:"vercel",sandboxId:p,retryable:b==="quota"||b==="unavailable"})}function N(i){throw new e(`${i}. Vercel cannot enforce this request. Use the supported Vercel settings or another provider.`,{code:"unsupported",provider:"vercel"})}var L="sandbox-sdk-key",j=(i)=>`sdk-${q("sha256").update(i).digest("hex")}`,M="flock -x /tmp/.sandbox-sdk-workspace-ready.lock sh -c 'if [ ! -f /tmp/.sandbox-sdk/prepared-workspace ]; then sudo mkdir -p /workspace && sudo chmod 777 /workspace && mkdir -p /tmp/.sandbox-sdk && touch /tmp/.sandbox-sdk/prepared-workspace || exit 1; fi' || exit 1",A="stat --printf '%n\\0%f %s %y\\0' --";function U(i){let p=i.split("\x00");if(p.pop()!==""||p.length%2)throw Error("Invalid Vercel file metadata");let l=[];for(let m=0;m<p.length;m+=2){let b=p[m],d=p[m+1]?.match(/^([0-9a-f]+) ([0-9]+) (.+)$/);if(b===void 0||!d)throw Error("Invalid Vercel stat response");let g=Number.parseInt(d[1]??"",16),C=Number(d[2]),_=Date.parse(d[3]??"");if(![g,C,_].every(Number.isFinite))throw Error("Invalid Vercel stat fields");l.push({path:b,type:(g&61440)===40960?"symlink":(g&61440)===16384?"directory":"file",size:C,modifiedAt:_})}return l}var B='for d in /tmp/.sandbox-sdk/procs/*; do [ -f "$d/spec.json" ] && [ ! -f "$d/exit" ] && printf 137 > "$d/exit"; done; rm -rf /tmp/.sandbox-sdk/runs; true';function z(i,p={}){let l=new Map,m=new Set,b,T=()=>b??=i(),d=async(r,n)=>{try{return await n()}catch(a){throw k(a,r)}};function g(){let r=p.token??process.env.VERCEL_TOKEN,n=p.teamId??process.env.VERCEL_TEAM_ID,a=p.projectId??process.env.VERCEL_PROJECT_ID;if(r){if(!n||!a)throw new e("Vercel credentials are incomplete. Token authentication requires teamId and projectId. Set VERCEL_TEAM_ID and VERCEL_PROJECT_ID.",{code:"auth",provider:"vercel"});return{token:r,teamId:n,projectId:a}}return{}}let C=async(r,n=!1)=>{if((await(await r.runCommand({cmd:"sh",args:["-c",B+(n?"; mkdir -p /tmp/.sandbox-sdk && touch /tmp/.sandbox-sdk/prepared-workspace":"")],detached:!0})).wait()).exitCode!==0)throw Error("Could not invalidate restored processes")},_=(r)=>{let n=l.get(r);if(!n)throw new e("Sandbox is not attached. No local native object exists. Connect the sandbox first.",{code:"not_found",provider:"vercel",sandboxId:r});return n};function P(r){let n={...r.tags},a=n[L];return delete n[L],{id:r.name,key:a,labels:n,createdAt:r.createdAt.getTime(),state:r.status==="running"||r.status==="pending"?"running":r.status==="stopped"?"paused":"stopped"}}let S=async(r,n=!1)=>{let a=await T(),s=await a.get({...g(),name:r,resume:n,onResume:C}),c=Date.now()+60000;while(s.tags?.["sandbox-sdk"]==="pending"){if(Date.now()>=c)throw new e("Sandbox initialization is incomplete. The creator has not finished setup. Retry connection later.",{code:"unavailable",provider:"vercel",sandboxId:r,retryable:!0});await new Promise((u)=>setTimeout(u,25)),s=await a.get({...g(),name:r,resume:!1,onResume:C})}return l.set(r,s),s},h=async(r)=>l.get(r)??S(r);function F(r){if(r===void 0)return;if(typeof r==="string")return{vcpus:{small:1,medium:2,large:4}[r]};N("Custom sizes are unavailable; Vercel exposes only vCPUs with 2048 MiB RAM per vCPU and no disk allocation control")}let D=async(r,n)=>{let a=await(await h(r)).fs.lstat(n);return{path:n,type:a.isSymbolicLink()?"symlink":a.isDirectory()?"directory":"file",size:a.size,modifiedAt:a.mtimeMs}};async function V(r,n,a,s){if(m.has(r)||!(a[0]==="/workspace"||a[0]?.startsWith("/workspace/")))return;let u=await(await h(r)).runCommand({cmd:"sh",args:["-c",`${M}; ${n}`,"sh",...a],cwd:"/",env:{LC_ALL:"C"},stdin:s===void 0?!1:R.from([s]),detached:!0}),I="",y="",f=(async()=>{for await(let x of u.logs())if(x.stream==="stdout")I+=x.data;else y+=x.data})(),[E]=await Promise.all([u.wait(),f]);if(E.exitCode!==0){if(/No such file or directory/.test(y))throw k({code:"ENOENT"},r);if(/Not a directory|Directory not empty/.test(y))throw k({code:"ENOTDIR"},r);throw Error("Vercel workspace or file operation failed")}return m.add(r),I}async function K(r,n,a){let s=`/tmp/sandbox-sdk-${crypto.randomUUID()}.pid`,c=`${s}.error`,u=`${m.has(r.name)?"":`(${M}) || { echo setup-error > ${t(c)}; exit 125; }; `}cd ${t(n.cwd)} || { echo cwd-error > ${t(c)}; exit 125; }; exec sh -c ${t(n.command)}`,I=`echo $$ > ${t(s)}; exec timeout --signal=KILL ${a/1000}s sh -c ${t(u)}`,y=await r.runCommand({cmd:"setsid",args:["--wait","sh","-c",I],cwd:"/",env:n.env,stdin:n.stdin===void 0?!1:R.from([n.stdin]),detached:!0}),f;try{for(let w=0;w<200;w++){try{if(f=Number((await r.fs.readFile(s)).toString()),Number.isInteger(f)&&f>0)break}catch(v){if(k(v,r.name).code!=="file_not_found")throw v}await new Promise((v)=>setTimeout(v,5))}if(!f||!Number.isInteger(f))throw await y.kill("SIGKILL"),new e("Command launch could not be confirmed. Remote process ID was unavailable. Reconnect and inspect the sandbox.",{code:"outcome_unknown",provider:"vercel"});await r.fs.rm(s,{force:!0})}catch(w){let v=f&&Number.isInteger(f)&&f>0?String(f):`$(cat ${t(s)})`;if((await(await r.runCommand({cmd:"sh",args:["-c",`pid=${v}; case "$pid" in ''|*[!0-9]*) exit 1;; esac; kill -KILL -"$pid" 2>/dev/null || true`],detached:!0})).wait()).exitCode!==0)throw new e("Command launch cleanup could not be confirmed. The remote PID is unavailable. Inspect or destroy the sandbox.",{code:"outcome_unknown",provider:"vercel",sandboxId:r.name});throw await y.wait(),w}let E=f;return{command:y,pid:f,kill:async(w)=>{await(await r.runCommand({cmd:"sh",args:["-c",`kill -${w} -${E} 2>/dev/null || true`],detached:!0})).wait()},errorPath:c}}return{name:"vercel",keyMode:"exact",capabilities:new Set(["pause","snapshot","network-policy","size"]),native:_,create:(r)=>d(void 0,async()=>{if(r.timeoutMs!==void 0)N("A hard lifetime across persistent sessions is unavailable; Vercel timeout resets on resume");if(r.idleTimeoutMs!==void 0)N("idleTimeoutMs is not exposed by the Vercel SDK");let n={...r.labels,"sandbox-sdk":"1",...r.key===void 0?{}:{[L]:r.key}};if(Object.keys(n).length>5)N("Vercel supports at most five tags, including sandbox-sdk and sandbox-sdk-key");if(new Set(r.ports).size>15)N("Vercel supports at most fifteen declared ports");let a={...g(),name:r.key===void 0?`sdk-${crypto.randomUUID()}`:j(r.key),persistent:!0,env:r.env,tags:n,ports:r.ports,resources:F(r.size),networkPolicy:r.network==="none"?"deny-all":typeof r.network==="object"?{allow:r.network.allow}:"allow-all",signal:r.signal,onResume:C},s={...a,tags:{...n,"sandbox-sdk":"pending"}},c=await(await T()).create(r.from?{...s,source:{type:"snapshot",snapshotId:r.from}}:a);l.set(c.name,c);try{if(!r.from)return P(c);if((await(await c.runCommand({cmd:"sh",args:["-c","mkdir -p /workspace && chmod 777 /workspace"],sudo:!0,detached:!0})).wait()).exitCode!==0)throw Error("Could not initialize /workspace");return await C(c,!0),await c.update({tags:n}),m.add(c.name),P(c)}catch(u){throw await c.delete(),l.delete(c.name),u}}),find:(r)=>d(void 0,async()=>{try{let n=await S(j(r));return n.tags?.["sandbox-sdk"]==="1"&&n.tags[L]===r?P(n):void 0}catch(n){if(k(n).code==="not_found")return;throw n}}),connect:(r)=>d(r,async()=>P(await S(r))),list:(r)=>d(void 0,async()=>{let n=[];for await(let a of await(await T()).list({...g(),tags:{"sandbox-sdk":"1"}}))try{let s=P(await S(a.name));if(s.labels["sandbox-sdk"]==="1"&&Object.entries(r).every(([c,u])=>s.labels[c]===u))n.push(s)}catch(s){if(k(s,a.name).code!=="not_found")throw s}return n}),destroy:(r)=>d(r,async()=>{try{await(await h(r)).delete()}catch(n){if(k(n).code!=="not_found")throw n}l.delete(r),m.delete(r)}),exec:(r,n)=>d(r,async()=>{if(n.signal?.aborted)return{exitCode:null,timedOut:!0};let a=Date.now(),s=await h(r),c=await K(s,n,n.timeoutMs),u=!1,I,y=()=>{u=!0,I??=c.kill("KILL"),I.catch(()=>{})};n.signal?.addEventListener("abort",y,{once:!0});let f=setTimeout(y,Math.max(0,n.timeoutMs-(Date.now()-a)));if(n.signal?.aborted)y();try{let E=(async()=>{for await(let w of c.command.logs())n.onChunk({stream:w.stream,text:w.data})})(),[x]=await Promise.all([c.command.wait(),E]);if(x.exitCode===137&&Date.now()-a>=n.timeoutMs)u=!0;if(await I,!u&&x.exitCode===125){let w;try{w=(await s.fs.readFile(c.errorPath)).toString().trim()}catch(v){if(k(v,r).code!=="file_not_found")throw v}if(w!==void 0)throw await s.fs.rm(c.errorPath,{force:!0}),new e("Command could not start. Workspace initialization or the requested working directory failed. Check the directory and sandbox permissions.",{code:w==="cwd-error"?"invalid_argument":"provider",provider:"vercel",sandboxId:r})}if(!u&&x.exitCode===0)m.add(r);return{exitCode:u?null:x.exitCode,timedOut:u}}catch(E){throw await c.kill("KILL"),await c.command.wait(),E}finally{clearTimeout(f),n.signal?.removeEventListener("abort",y)}}),files:{writeCreatesParents:!0,read:(r,n)=>d(r,async()=>{let a=await V(r,'base64 -- "$1"',[n]);return a===void 0?new Uint8Array(await(await h(r)).fs.readFile(n)):new Uint8Array(Buffer.from(a,"base64"))}),write:(r,n,a)=>d(r,async()=>{if(await V(r,'mkdir -p -- "$(dirname -- "$1")" && cat > "$1"',[n],a)!==void 0)return;let s=await h(r);await s.fs.mkdir(O.dirname(n),{recursive:!0}),await s.fs.writeFile(n,a)}),stat:(r,n)=>d(r,async()=>{let a=await V(r,`${A} "$1"`,[n]);if(a===void 0)return D(r,n);let s=U(a)[0];if(!s)throw Error("Missing Vercel stat response");return s}),list:(r,n)=>d(r,async()=>{let a=await V(r,`if [ ! -d "$1" ]; then if [ -e "$1" ] || [ -L "$1" ]; then echo 'Not a directory' >&2; else echo 'No such file or directory' >&2; fi; exit 1; fi; find -H "$1" -mindepth 1 -maxdepth 1 -exec ${A} {} +`,[n]);if(a===void 0)return Promise.all((await(await h(r)).fs.readdir(n)).map((s)=>D(r,O.join(n,s))));return U(a)}),mkdir:(r,n)=>d(r,async()=>{if(await V(r,'mkdir -p -- "$1"',[n])!==void 0)return;await(await h(r)).fs.mkdir(n,{recursive:!0})}),remove:(r,n,a)=>d(r,async()=>{if(await V(r,'if [ "$2" = true ]; then rm -r -- "$1"; else rm -- "$1"; fi',[n,String(a.recursive)])!==void 0)return;await(await h(r)).fs.rm(n,{recursive:a.recursive})})},previewUrl:(r,n)=>d(r,async()=>{let a=await h(r);if(!a.routes.some((s)=>s.port===n))throw new e(`Port ${n} was not declared at creation. Vercel needs ports in CreateInput. Recreate with ports: [${n}].`,{code:"invalid_argument",provider:"vercel",sandboxId:r});return{url:a.domain(n)}}),close:async(r)=>{l.delete(r),m.delete(r)},pause:(r)=>d(r,async()=>{await(await h(r)).stop()}),resume:(r)=>d(r,async()=>{await S(r,!0)}),snapshot:(r)=>d(r,async()=>({id:(await(await h(r)).snapshot()).snapshotId}))}}function ae(i={}){return z(async()=>{let{Sandbox:p}=await o("@vercel/sandbox","vercel",()=>import("@vercel/sandbox"));return p},i)}export{ae as vercel};

package/dist/providers/vercel/provider.d.ts

@@ -0,0 +1,10 @@
+import type { Provider } from "../../provider.js";
+import type { NativeSandbox, VercelClient } from "./transport.js";
+export interface VercelOptions {
+    token?: string;
+    teamId?: string;
+    projectId?: string;
+}
+export type VercelCapability = "pause" | "snapshot" | "network-policy" | "size";
+/** Internal injection point used by the offline SDK contract tests. */
+export declare function createVercelProvider<N extends NativeSandbox>(load: () => Promise<VercelClient<N>>, options?: VercelOptions): Provider<N, VercelCapability>;

package/dist/providers/vercel/transport.d.ts

@@ -0,0 +1,40 @@
+import type { Sandbox, Command } from "@vercel/sandbox";
+import type { Stats } from "node:fs";
+export type NativeCommand = Pick<Command, "cmdId" | "kill"> & {
+    wait(): Promise<Pick<Awaited<ReturnType<Command["wait"]>>, "exitCode">>;
+    logs(): AsyncIterable<{
+        stream: "stdout" | "stderr";
+        data: string;
+    }>;
+};
+/** SDK-derived transport slice, structurally checked against the real SDK loader. */
+export type NativeSandbox = Pick<Sandbox, "name" | "status" | "tags" | "routes" | "createdAt" | "cwd" | "domain" | "delete" | "update"> & {
+    fs: Pick<Sandbox["fs"], "writeFile" | "mkdir" | "rm"> & {
+        readFile(path: string): Promise<Buffer>;
+        readdir(path: string): Promise<string[]>;
+        lstat(path: string): Promise<Stats>;
+    };
+    stop(): Promise<unknown>;
+    snapshot(): Promise<Pick<Awaited<ReturnType<Sandbox["snapshot"]>>, "snapshotId">>;
+    runCommand(params: Parameters<Sandbox["runCommand"]>[0] & {
+        detached: true;
+    }): Promise<NativeCommand>;
+};
+export interface VercelClient<N extends NativeSandbox> {
+    create(params: NonNullable<Parameters<typeof Sandbox.create>[0]> & {
+        onResume?: (box: N) => Promise<void>;
+    }): Promise<N>;
+    get(params: Parameters<typeof Sandbox.get>[0] & {
+        onResume?: (box: N) => Promise<void>;
+    }): Promise<N>;
+    list(params: {
+        tags: {
+            "sandbox-sdk": string;
+        };
+        token?: string;
+        teamId?: string;
+        projectId?: string;
+    }): Promise<AsyncIterable<{
+        name: string;
+    }>>;
+}

package/dist/run.d.ts

@@ -0,0 +1,41 @@
+import type { OutputChunk, Provider } from "./provider.js";
+import { Redactor } from "./errors.js";
+import type { RunHandle, RunOptions } from "./types.js";
+export declare const defaults: {
+    CI: string;
+    PAGER: string;
+    GIT_TERMINAL_PROMPT: string;
+    DEBIAN_FRONTEND: string;
+    TERM: string;
+    NO_COLOR: string;
+};
+export declare const pathOf: (path?: string) => string;
+export declare const quote: (value: unknown) => string;
+export declare const secretRecoveryCommand = "if [ -f /tmp/.sandbox-sdk/secret-names.json ]; then cat /tmp/.sandbox-sdk/secret-names.json || exit 1; printf '\\000'; env -0; fi";
+export declare const isRunActive: (provider: string, id: string) => boolean;
+export declare class BufferCap {
+    readonly limit: number;
+    private head;
+    private tail;
+    total: number;
+    constructor(limit: number);
+    add(text: string): void;
+    get truncated(): boolean;
+    text(): string;
+}
+/** Bounded independent subscriptions; slow consumers see the most recent 1 MB. */
+export declare class OutputBus {
+    private listeners;
+    private ended;
+    private failure;
+    emit(chunk: OutputChunk): void;
+    fail(error: unknown): void;
+    end(): void;
+    stream(): AsyncGenerator<OutputChunk>;
+}
+/** Hold suffixes so secrets split between transport chunks never escape. */
+export declare function chunkRedactor(redactor: Redactor, emit: (chunk: OutputChunk) => void, interleaved?: boolean): {
+    push(chunk: OutputChunk): void;
+    flush(): void;
+};
+export declare function makeRun(provider: Provider, id: string, redactor: Redactor, baseEnv: Record<string, string>, count: (bytes: number) => void, guard?: () => void): (command: string, initial?: RunOptions) => RunHandle;

package/dist/testing.d.ts

@@ -0,0 +1,17 @@
+import type { Provider } from "./provider.js";
+/** Register a provider-independent Vitest suite. Call inside a test module.
+ * live must be explicitly true to run a cloud provider. memory skips real git
+ * and HTTP probes, since it never executes host programs or opens sockets.
+ * Live runs give each case 120 seconds by default, since real providers boot
+ * machines and cross the network; pass timeoutMs to change it.
+ */
+export declare function runConformance(factory: () => Provider | Promise<Provider>, options: {
+    live: boolean;
+    ports?: number[];
+    timeoutMs?: number;
+    unsupported?: {
+        processes?: string;
+        previews?: string;
+        gitPush?: string;
+    };
+}): void;

package/dist/testing.js

@@ -0,0 +1,6 @@
+import{p,g,S,E}from"./chunk-59t3rqja.js";import{e}from"./chunk-gc8zdxyb.js";import{describe as y,test as n,expect as a,afterEach as x}from"vitest";import{mkdtemp as k,mkdir as B,writeFile as b,readFile as O,rm as j}from"node:fs/promises";import{tmpdir as M}from"node:os";import{join as w}from"node:path";function A(f,c){let v=c.timeoutMs??(c.live?120000:void 0);y("Sandbox SDK conformance",{timeout:v},()=>{let u=[],h=[];async function d(t={}){let i=await f();if(!c.live&&!["memory","local"].includes(i.name))throw new e("Live provider refused. live is false. Enable live explicitly with provider credentials.",{code:"invalid_argument"});let o=await p(i,{ports:c.ports,...t});return u.push(o),{provider:i,box:o}}x(async()=>{await Promise.all(u.splice(0).map((t)=>t.destroy())),await Promise.all(h.splice(0).map((t)=>j(t,{recursive:!0,force:!0})))}),n("create, key lookup, connect and labels",async()=>{let t=await f();if(!c.live&&!["memory","local"].includes(t.name))throw Error("live must be enabled");let i=`conformance-${crypto.randomUUID()}`,o=await p(t,{key:i,labels:{suite:i}});u.push(o);let s=await p(t,{key:i});u.push(s),a(o.created).toBe(!0),a(s.created).toBe(!1),a(s.id).toBe(o.id);let r=await g(t,o.id);u.push(r),a(r.native).toBeDefined(),await a.poll(async()=>(await S(t,{labels:{suite:i}})).map((l)=>l.id),{timeout:15000,interval:500}).toEqual([o.id])}),n("exit results, stdin, resolved cwd and default environment",async()=>{let{box:t}=await d();a(await t.run("false")).toMatchObject({ok:!1,exitCode:1,timedOut:!1}),a(await t.run("exit 7")).toMatchObject({exitCode:7}),a((await t.run("cat",{stdin:`input
+`})).stdout).toBe(`input
+`),a((await t.run("pwd")).stdout).toBe(`/workspace
+`),a((await t.run(`printf '%s' "$CI:$PAGER:$GIT_TERMINAL_PROMPT:$DEBIAN_FRONTEND:$TERM:$NO_COLOR"`)).stdout).toBe("1:cat:0:noninteractive:dumb:1")}),n("timeout and abort kill work before following side effects",async()=>{let{box:t}=await d(),i=await t.run("sleep 1; echo survived > survived",{timeoutMs:20});a(i).toMatchObject({timedOut:!0,exitCode:null,ok:!1});let o=new AbortController,s=t.run("sleep 1; echo survived > aborted",{signal:o.signal}),r=Promise.resolve(s);setTimeout(()=>o.abort(),20),a(await r).toMatchObject({timedOut:!0,exitCode:null}),a(await t.files.exists("survived")).toBe(!1),a(await t.files.exists("aborted")).toBe(!1)}),n("bounded head and tail output, interleaving and streaming",async()=>{let{box:t}=await d(),i=await t.run(`printf '${"a".repeat(1024)}END'`,{maxOutputBytes:64});a(i.truncated).toBe(!0),a(i.stdout.startsWith("a")).toBe(!0),a(i.stdout.endsWith("END")).toBe(!0),a(i.stdout).toContain("bytes cut");let o=t.run("printf A; printf B >&2; printf C"),s=[];for await(let m of o)s.push(m.text);let r=await o;a(r).toMatchObject({stdout:"AC",stderr:"B",output:s.join("")});let l=[];for await(let m of t.run("echo streamed"))l.push(m.text);a(l.join("")).toBe(`streamed
+`)}),n("tag escaping and chain options prevent interpolation execution",async()=>{let{box:t}=await d(),i="x'; echo injected; printf '";a((await t.$`printf '%s' ${"x'; echo injected; printf '"}`.cwd(".").env({X:"ok"}).timeout(c.live?1e4:1000)).stdout).toBe("x'; echo injected; printf '"),a((await t.run(`printf '%s' "$X"`)).stdout).toBe("")}),n("all file primitives, exact edits, glob search, checkpoints",async()=>{let{box:t}=await d({trackChanges:!0});await t.files.write({"app/a.ts":`TODO one
+second`,"app/b.ts":"two two","app/raw":new Uint8Array([0,255])}),a(await t.files.read("app/raw",{as:"bytes"})).toEqual(new Uint8Array([0,255])),a((await t.files.stat("app/a.ts")).type).toBe("file"),a((await t.files.list("app",{recursive:!0,glob:"**/*.ts"})).length).toBe(2),a(await t.files.search("TODO",{path:"app",glob:"*.ts"})).toMatchObject([{line:1,text:"TODO one"}]),await a(t.files.edit("app/a.ts",{find:"missing",replace:"x"})).rejects.toMatchObject({code:"edit_not_found"}),await a(t.files.edit("app/b.ts",{find:"two",replace:"x"})).rejects.toMatchObject({code:"edit_not_unique"});let i=await t.files.mark();await t.files.edit("app/a.ts",{find:"TODO",replace:"DONE"}),await t.files.remove("app/b.ts"),await t.files.write("app/new","new"),a(await t.files.changes({since:i})).toMatchObject({added:["/workspace/app/new"],modified:["/workspace/app/a.ts"],removed:["/workspace/app/b.ts"]}),a((await t.files.changes()).added).toContain("/workspace/app/a.ts"),await t.files.remove("app",{recursive:!0}),a(await t.files.exists("app")).toBe(!1)}),n("changes without since needs trackChanges or an explicit mark",async()=>{let{box:t}=await d();await a(t.files.changes()).rejects.toMatchObject({code:"invalid_argument",message:a.stringContaining("trackChanges: true")}),await t.files.write("late","x");let i=await t.files.mark("start");await t.files.write("late","y"),a((await t.files.changes()).modified).toEqual(["/workspace/late"]),a((await t.files.changes({since:i})).modified).toEqual(["/workspace/late"])}),n("upload/download round trip with ignores",async()=>{let{box:t}=await d(),i=await k(w(M(),"sdk-conformance-"));h.push(i),await B(w(i,"source")),await b(w(i,"source","keep"),"hello"),await b(w(i,"source","ignore"),"no"),await t.files.upload(w(i,"source"),"upload",{ignore:["ignore"]}),a(await t.files.exists("upload/ignore")).toBe(!1),await t.files.download("upload",w(i,"download")),a(await O(w(i,"download","keep"),"utf8")).toBe("hello")}),n("file watch observes changes",async()=>{let{box:t}=await d();await t.files.write("watch/file","a");let i=[],o=t.files.watch("watch",(r)=>i.push(r.type),{recursive:!0,intervalMs:10}),s=0;try{await a.poll(async()=>(await t.files.write("watch/file",`different-${s++}`),i),{timeout:1e4,interval:50}).toContain("modified")}finally{o()}}),n("process logs, cursors, fresh client reattach, stop and exit-before-ready",async(t)=>{if(c.unsupported?.processes){t.skip(c.unsupported.processes);return}let{provider:i,box:o}=await d(),s=await o.start("echo READY; sleep 5",{name:"dev",ready:{log:/READY/},readyTimeoutMs:2000});a(s.ready).toBe(!0);let r=await s.logs();a(r.text).toContain("READY"),a((await s.logs({after:r.nextCursor})).text).toBe("");let l=await g(i,o.id);u.push(l),a((await l.processes()).map((m)=>m.name)).toContain("dev"),a((await l.process("dev").logs()).text).toContain("READY"),await l.process("dev").stop({graceMs:10}),a((await s.wait()).exitCode).not.toBe(null),await a(o.start("exit 3",{name:"early",ready:{log:/never/},readyTimeoutMs:1000})).rejects.toMatchObject({code:"process_exited"})}),n("readiness timeout preserves the process",async(t)=>{if(c.unsupported?.processes){t.skip(c.unsupported.processes);return}let{box:i}=await d();await a(i.start("sleep 5",{name:"unready",ready:{log:/never/},readyTimeoutMs:30})).rejects.toMatchObject({code:"timeout"}),a(i.process("unready").ready).toBe(!1),a((await i.processes())[0]?.status).toBe("running"),await i.process("unready").stop({graceMs:10})}),n("preview and capability gating",async()=>{let{provider:t,box:i}=await d();if(c.unsupported?.previews)await a(i.preview(3000)).rejects.toMatchObject({code:"unsupported"});else a(["http:","https:"]).toContain(new URL((await i.preview(3000)).url).protocol);for(let[o,s]of[["pause","pause"],["snapshot","snapshot"],["terminal","terminal"]])a(s in i).toBe(t.capabilities.has(o));if(!t.capabilities.has("network-policy"))await a(p(t,{network:"none"})).rejects.toMatchObject({code:"unsupported"});if(!t.capabilities.has("size"))await a(p(t,{size:"small"})).rejects.toMatchObject({code:"unsupported"})}),n("close, disposal, destroy and label-scoped reaping",async()=>{let{provider:t,box:i}=await d(),o=i.id;await i.close(),a((await g(t,o)).id).toBe(o),await i.destroy(),await a(g(t,o)).rejects.toMatchObject({code:"not_found"});let s=crypto.randomUUID(),r=await p(t,{key:s,labels:{reap:s}});u.push(r),await r[Symbol.asyncDispose](),a((await t.connect(r.id)).id).toBe(r.id),a(await E(t,{labels:{reap:s},olderThanMs:0})).toBe(1);let l=await p(t);await l[Symbol.asyncDispose](),await a(t.connect(l.id)).rejects.toMatchObject({code:"not_found"})}),n("usage counters",async()=>{let{box:t}=await d();await t.run("echo abc"),a(await t.usage()).toMatchObject({commands:1,bytesOut:4})}),n("local bare git clone, commit and push (live providers only)",async(t)=>{if(c.unsupported?.gitPush){t.skip(c.unsupported.gitPush);return}let{provider:i,box:o}=await d();if(i.name==="memory"){t.skip();return}a((await o.run("git init --bare /tmp/sdk-bare")).ok).toBe(!0),a((await o.git.clone("/tmp/sdk-bare",{dir:"repo"})).ok).toBe(!0),await o.run("git config user.name Conformance; git config user.email test@example.com",{cwd:"repo"}),await o.files.write("repo/test","test"),a((await o.git.commit("repo",{message:"conformance",all:!0})).ok).toBe(!0),a((await o.git.status("repo")).stdout).toBe(""),a((await o.git.push("repo",{branch:"HEAD"})).ok).toBe(!0)}),n("real HTTP preview probe (live Linux providers only)",async(t)=>{if(c.unsupported?.previews){t.skip(c.unsupported.previews);return}let{provider:i,box:o}=await d();if(i.name==="memory"){t.skip();return}let s=await o.start(`node -e 'require("http").createServer((_,r)=>r.end("ok")).listen(3000,"0.0.0.0")'`,{name:"http",ready:{http:{port:3000}}});a(s.ready).toBe(!0),a((await o.preview(3000,{waitMs:2000})).url).toBeTruthy(),await s.stop()})})}export{A as runConformance};

package/dist/tool-security.d.ts

@@ -0,0 +1,9 @@
+import type { Redactor } from "./errors.js";
+import type { OutputChunk } from "./types.js";
+export declare function registerToolRedactor(box: object, redactor: Redactor): void;
+export declare function redactToolText(box: object, text: string): string;
+/** ANSI sequences and secrets can both cross transport boundaries. Normalize before redacting. */
+export declare function toolOutputFilter(box: object, emit: (chunk: OutputChunk) => void): {
+    push(chunk: OutputChunk): undefined;
+    flush(): void;
+};

package/dist/tools.d.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import type { Sandbox, OutputChunk } from "./types.js";
+export declare const toolSchemas: {
+    run: z.ZodObject<{
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    read_file: z.ZodObject<{
+        path: z.ZodString;
+        offset: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    write_file: z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strict>;
+    edit_file: z.ZodObject<{
+        path: z.ZodString;
+        find: z.ZodString;
+        replace: z.ZodString;
+    }, z.core.$strict>;
+    start_process: z.ZodObject<{
+        name: z.ZodString;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    process_logs: z.ZodObject<{
+        name: z.ZodString;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    stop_process: z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strict>;
+    search: z.ZodObject<{
+        query: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        glob: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    list_files: z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        glob: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    changes: z.ZodObject<{}, z.core.$strict>;
+    preview: z.ZodObject<{
+        port: z.ZodNumber;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+};
+export type ToolName = keyof typeof toolSchemas;
+export type ToolParameters = z.infer<(typeof toolSchemas)[ToolName]>;
+export type ToolEvent = {
+    tool: ToolName;
+    kind: "output";
+    stream: OutputChunk["stream"];
+    text: string;
+};
+export interface ToolLimits {
+    maxOutputBytes?: number;
+    timeoutMs?: number;
+    maxReadBytes?: number;
+    maxMatches?: number;
+}
+export interface SandboxToolsOptions {
+    /** Resolves file paths and cwd. Shell commands still have the sandbox's full privileges. */
+    root?: string;
+    allow?: readonly ToolName[];
+    deny?: readonly ToolName[];
+    beforeRun?: (command: string) => boolean | string | Promise<boolean | string>;
+    limits?: Partial<Record<ToolName, ToolLimits>>;
+    onEvent?: (event: ToolEvent) => void;
+}
+export interface ToolResult {
+    text: string;
+}
+export declare function createSandboxTools(box: Sandbox, options?: SandboxToolsOptions): {
+    name: "run" | "read_file" | "write_file" | "edit_file" | "start_process" | "process_logs" | "stop_process" | "search" | "list_files" | "changes" | "preview";
+    description: string;
+    inputSchema: z.ZodObject<{
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict> | z.ZodObject<{
+        path: z.ZodString;
+        offset: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict> | z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strict> | z.ZodObject<{
+        path: z.ZodString;
+        find: z.ZodString;
+        replace: z.ZodString;
+    }, z.core.$strict> | z.ZodObject<{
+        name: z.ZodString;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict> | z.ZodObject<{
+        name: z.ZodString;
+        cursor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict> | z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strict> | z.ZodObject<{
+        query: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        glob: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict> | z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        glob: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict> | z.ZodObject<{}, z.core.$strict> | z.ZodObject<{
+        port: z.ZodNumber;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    execute(input: unknown, emit?: ((event: ToolEvent) => void) | undefined, signal?: AbortSignal): Promise<ToolResult>;
+}[];

package/dist/tools.js

@@ -0,0 +1 @@
+import{c,w}from"./chunk-v6y7eqxw.js";import"./chunk-cwx6cc31.js";import"./chunk-t5vr9nd8.js";export{w as createSandboxTools,c as toolSchemas};