@evolvingmachines/modal 0.0.52-sable-rename.20260803.6ab54d4 → 0.0.53
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -1
- package/dist/index.cjs +4 -4
- package/dist/index.d.cts +5 -397
- package/dist/index.d.ts +5 -397
- package/dist/index.js +4 -4
- package/package.json +3 -4
package/README.md
CHANGED
|
@@ -1,4 +1,8 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/evolving-machines-lab/evolve/main/logo/evolving-machines-ink.png" alt="Evolving Machines" width="380">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# Evolving Machines — Evolve Modal Provider
|
|
2
6
|
|
|
3
7
|
Modal sandbox provider for [Evolve SDK](https://www.npmjs.com/package/@evolvingmachines/sdk).
|
|
4
8
|
|
package/dist/index.cjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
'use strict';var modal=require('modal'),tarStream=require('tar-stream');var
|
|
2
|
-
`).slice(1).map(
|
|
3
|
-
`)){if(!
|
|
4
|
-
exports.
|
|
1
|
+
'use strict';var modal=require('modal'),tarStream=require('tar-stream');var b={"evolve-all":"evolvingmachines/evolve-all"},h=new Set([".xlsx",".xls",".docx",".doc",".pptx",".ppt",".pdf",".zip",".tar",".gz",".7z",".rar",".png",".jpg",".jpeg",".gif",".webp",".ico",".bmp",".mp3",".wav",".ogg",".flac",".aac",".mp4",".avi",".mov",".mkv",".webm",".woff",".woff2",".ttf",".otf",".eot",".exe",".dll",".so",".dylib",".sqlite",".db",".pickle",".pkl",".parquet"]);function y(c){let t=c.substring(c.lastIndexOf(".")).toLowerCase();return h.has(t)}var u=class{constructor(t){this.sandbox=t;}wrapAsUser(t,e,n){let r="";n&&Object.keys(n).length>0&&(r=Object.entries(n).filter(([,o])=>o!=null).map(([o,i])=>`export ${o}='${String(i).replace(/'/g,"'\\''")}'`).join("; ")+"; ");let s=e?`cd '${e.replace(/'/g,"'\\''")}' && ${r}${t}`:`${r}${t}`;return ["su","user","-c",`echo ${Buffer.from(s).toString("base64")} | base64 -d | bash`]}async run(t,e){let n=this.wrapAsUser(t,e?.cwd,e?.envs),r=await this.sandbox.exec(n,{timeoutMs:e?.timeoutMs}),{stdout:s,stderr:a}=await this.accumulateStreams(r,e?.onStdout,e?.onStderr);return {exitCode:await r.wait(),stdout:s,stderr:a}}async spawn(t,e){let n=this.wrapAsUser(t,e?.cwd,e?.envs),r=await this.sandbox.exec(n,{timeoutMs:e?.timeoutMs}),s="",a="",o=this.accumulateStreams(r,e?.onStdout?d=>{e.onStdout(d);}:void 0,e?.onStderr?d=>{e.onStderr(d);}:void 0).then(({stdout:d,stderr:m})=>{s=d,a=m;}).catch(()=>{});return {processId:`modal-${Date.now()}-${Math.random().toString(36).slice(2)}`,wait:async()=>(await o,{exitCode:await r.wait(),stdout:s,stderr:a}),kill:async()=>false}}async list(){let t=await this.sandbox.exec(["ps","-eo","pid,comm,args"],{timeoutMs:1e4});return await t.wait(),(await t.stdout.readText()).trim().split(`
|
|
2
|
+
`).slice(1).map(r=>{let s=r.trim().split(/\s+/);return {processId:s[0],cmd:s[1]||"",args:s.slice(2),envs:{}}})}async connect(t,e){throw new Error("Modal does not support connecting to existing processes")}async sendStdin(t,e){throw new Error("Modal does not support sendStdin by process ID")}async kill(t){return await(await this.sandbox.exec(["kill","-9",t],{timeoutMs:1e4})).wait()===0}async accumulateStreams(t,e,n){let r="",s="",a=[];return a.push((async()=>{try{for await(let o of t.stdout){let i=typeof o=="string"?o:new TextDecoder().decode(o);r+=i,e?.(i);}}catch{}})()),a.push((async()=>{try{for await(let o of t.stderr){let i=typeof o=="string"?o:new TextDecoder().decode(o);s+=i,n?.(i);}}catch{}})()),await Promise.all(a),{stdout:r,stderr:s}}},g=class{constructor(t){this.sandbox=t;}async read(t){if(y(t)){let r=await this.sandbox.exec(["cat",t],{timeoutMs:3e5,mode:"binary"}),s=await r.wait();if(s!==0){let a=await r.stderr.readText();throw new Error(`Failed to read file ${t}: ${a||`exit code ${s}`}`)}return await r.stdout.readBytes()}let e=await this.sandbox.exec(["cat",t],{timeoutMs:3e5}),n=await e.wait();if(n!==0){let r=await e.stderr.readText();throw new Error(`Failed to read file ${t}: ${r||`exit code ${n}`}`)}return await e.stdout.readText()}async write(t,e){let n=this.toBuffer(e),r=t.substring(0,t.lastIndexOf("/"));r&&await this.makeDir(r);let s=t.replace(/'/g,"'\\''"),a=await this.sandbox.exec(["bash","-c",`cat > '${s}'`],{mode:"binary"});await a.stdin.writeBytes(new Uint8Array(n)),await a.stdin.getWriter().close(),await a.wait(),await(await this.sandbox.exec(["chown","user:user",t],{timeoutMs:1e4})).wait();}async writeBatch(t){let e=tarStream.pack(),n=[],r=new Set;for(let i of t){let d=this.toBuffer(i.data),m=i.path.startsWith("/")?i.path.slice(1):i.path;e.entry({name:m},d);let p=i.path.substring(0,i.path.lastIndexOf("/"));p&&r.add(p);}e.finalize();for await(let i of e)n.push(Buffer.from(i));let s=Buffer.concat(n),a=await this.sandbox.exec(["tar","-xf","-","-C","/"],{mode:"binary"});if(await a.stdin.writeBytes(new Uint8Array(s)),await a.stdin.getWriter().close(),await a.wait(),r.size>0){let i=Array.from(r),d=new Set(i.map(m=>m.split("/").slice(0,4).join("/")));for(let m of d)await(await this.sandbox.exec(["chown","-R","user:user",m],{timeoutMs:3e4})).wait();}}async makeDir(t){await(await this.sandbox.exec(["mkdir","-p",t],{timeoutMs:1e4})).wait(),await(await this.sandbox.exec(["chown","-R","user:user",t],{timeoutMs:1e4})).wait();}async exists(t){return await(await this.sandbox.exec(["test","-e",t],{timeoutMs:1e4})).wait()===0}async list(t){let e=t.replace(/'/g,"'\\''"),n=await this.sandbox.exec(["bash","-c",`ls -la '${e}' | tail -n +2`],{timeoutMs:3e4});await n.wait();let r=await n.stdout.readText(),s=[];for(let a of r.trim().split(`
|
|
3
|
+
`)){if(!a)continue;let o=a.split(/\s+/);if(o.length<9)continue;let i=o[0],d=o.slice(8).join(" ");d==="."||d===".."||s.push({name:d,path:t.endsWith("/")?`${t}${d}`:`${t}/${d}`,type:i.startsWith("d")?"dir":"file"});}return s}async remove(t){await(await this.sandbox.exec(["rm","-rf",t],{timeoutMs:3e4})).wait();}async rename(t,e){await(await this.sandbox.exec(["mv",t,e],{timeoutMs:3e4})).wait();}async readStream(t){return (await this.sandbox.exec(["cat",t],{timeoutMs:3e5,mode:"binary"})).stdout}async writeStream(t,e){let n=t.substring(0,t.lastIndexOf("/"));n&&await this.makeDir(n);let r=t.replace(/'/g,"'\\''"),s=await this.sandbox.exec(["bash","-c",`cat > '${r}'`],{mode:"binary"}),a=e.getReader();try{for(;;){let{done:i,value:d}=await a.read();if(i)break;await s.stdin.writeBytes(d);}}finally{a.releaseLock();}await s.stdin.getWriter().close(),await s.wait();}async uploadUrl(t,e){throw new Error("Modal does not support pre-signed upload URLs")}async downloadUrl(t,e){throw new Error("Modal does not support pre-signed download URLs")}async watchDir(t,e,n){throw new Error("Modal does not support watchDir")}toBuffer(t){if(typeof t=="string")return Buffer.from(t,"utf-8");if(t instanceof Buffer)return t;if(t instanceof ArrayBuffer||t instanceof Uint8Array)return Buffer.from(t);throw new Error(`Unsupported data type: ${typeof t}`)}},l=class{constructor(t,e){this.sandbox=t;this.commands=new u(t),this.files=new g(t),this.image=e,this.startTime=new Date;}commands;files;image;startTime;get sandboxId(){return this.sandbox.sandboxId}async getHost(t){let n=(await this.sandbox.tunnels())[t];if(!n)throw new Error(`No tunnel found for port ${t}`);return n.url}async isRunning(){try{return await(await this.sandbox.exec(["echo","ping"],{timeoutMs:5e3})).wait(),!0}catch{return false}}async getInfo(){return {sandboxId:this.sandbox.sandboxId,image:this.image,metadata:{},startedAt:this.startTime.toISOString()}}async kill(){try{await this.sandbox.terminate();}catch{await new Promise(t=>setTimeout(t,500)),await this.sandbox.terminate();}}async pause(){throw new Error("Modal does not support pause. Use kill() instead.")}},w=class{providerType="modal";name="Modal";client;appName;defaultTimeoutMs;imageName;_app;constructor(t){!t.endpoint&&process.env.MODAL_SERVER_URL?.startsWith("unix:")?process.env.MODAL_SERVER_URL="https://api.modal.com:443":t.endpoint&&(process.env.MODAL_SERVER_URL=t.endpoint),this.client=new modal.ModalClient({tokenId:t.tokenId,tokenSecret:t.tokenSecret}),this.appName=t.appName??"evolve-sandbox",this.defaultTimeoutMs=t.defaultTimeoutMs??36e5,this.imageName=t.imageName??"evolve-all";}async getApp(){return this._app||(this._app=await this.client.apps.fromName(this.appName,{createIfMissing:true})),this._app}async create(t){let e=await this.getApp(),n=t.timeoutMs??this.defaultTimeoutMs,r=t.image||this.imageName,s=b[r]??r,o=await this.client.images.fromRegistry(s).build(e),i=t.envs?Object.fromEntries(Object.entries(t.envs).filter(([,p])=>p!=null)):void 0,d=i&&Object.keys(i).length>0?i:void 0,m=await this.client.sandboxes.create(e,o,{cpu:4,memoryMiB:4096,timeoutMs:n,workdir:t.workingDirectory,env:d});return t.workingDirectory&&await(await m.exec(["chown","-R","user:user",t.workingDirectory],{timeoutMs:3e4})).wait(),new l(m,s)}async connect(t,e){let n=await this.client.sandboxes.fromId(t);return new l(n,"unknown")}async list(t){let e=[],n=t?.limit??100;try{for await(let r of this.client.sandboxes.list())if(e.push({sandboxId:r.sandboxId,image:"unknown",metadata:{},startedAt:new Date().toISOString()}),e.length>=n)break}catch{}return e}};function k(c={}){let t=c.tokenId??process.env.MODAL_TOKEN_ID,e=c.tokenSecret??process.env.MODAL_TOKEN_SECRET;if(!t||!e)throw new Error("Modal credentials required. Set MODAL_TOKEN_ID and MODAL_TOKEN_SECRET environment variables, or pass tokenId/tokenSecret in config. Get your token at https://modal.com/settings/tokens");return new w({...c,tokenId:t,tokenSecret:e})}
|
|
4
|
+
exports.ModalProvider=w;exports.createModalProvider=k;
|
package/dist/index.d.cts
CHANGED
|
@@ -1,20 +1,7 @@
|
|
|
1
|
-
import { Sandbox } from 'modal';
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
* GENERATED — DO NOT EDIT. `npm run generate:image-version` (repo root)
|
|
5
|
-
* rewrites this file from the evolve-all image build inputs under
|
|
6
|
-
* assets/docker/ (see assets/docker/image-digest.ts for the derivation).
|
|
7
|
-
* The value is content-addressed: same inputs → same tag, any input
|
|
8
|
-
* change → a new tag. The coherence test in
|
|
9
|
-
* packages/daytona/tests/unit/daytona-image-version.test.ts fails the
|
|
10
|
-
* suite whenever this checked-in copy is stale.
|
|
11
|
-
*/
|
|
12
|
-
declare const EVOLVE_IMAGE_VERSION = "c-6cd57962a3d9";
|
|
13
|
-
|
|
14
1
|
/**
|
|
15
2
|
* Modal Sandbox Provider - Clean Architecture
|
|
16
3
|
*
|
|
17
|
-
* @requires modal >= 0.
|
|
4
|
+
* @requires modal >= 0.3.0
|
|
18
5
|
* @requires Node.js >= 18 (for ReadableStream support)
|
|
19
6
|
*
|
|
20
7
|
* Design principles:
|
|
@@ -26,149 +13,9 @@ declare const EVOLVE_IMAGE_VERSION = "c-6cd57962a3d9";
|
|
|
26
13
|
*
|
|
27
14
|
* Modal-specific notes:
|
|
28
15
|
* - No native file APIs - uses exec() with stdin/stdout
|
|
29
|
-
* - pause() not supported - throws error
|
|
16
|
+
* - pause() not supported - throws error
|
|
30
17
|
* - Requires app context for sandbox creation
|
|
31
|
-
* - Hard 24h sandbox lifetime cap (ModalSandboxLifetimeError when exceeded)
|
|
32
|
-
* - Everything executes as root inside the sandbox; the `user` option is
|
|
33
|
-
* enforced through an `su <user> -c` wrapper (default user: "user")
|
|
34
|
-
* - Network policy maps to Modal's blockNetwork / outboundDomainAllowlist /
|
|
35
|
-
* outboundCidrAllowlist (domain allowlist admits TLS on port 443 only —
|
|
36
|
-
* plaintext destinations must be listed as IPs/CIDRs)
|
|
37
|
-
* - Modal exposes no metadata or public timestamps on sandboxes; both are
|
|
38
|
-
* stamped into sandbox tags at create time and read back via getTags()
|
|
39
|
-
*/
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
* Modal's hard cap on sandbox lifetime (24 hours).
|
|
43
|
-
* Requests beyond this throw ModalSandboxLifetimeError.
|
|
44
|
-
*/
|
|
45
|
-
declare const MODAL_MAX_LIFETIME_MS: number;
|
|
46
|
-
/**
|
|
47
|
-
* Chunk size for stdin uploads. Modal's gRPC transport rejects any single
|
|
48
|
-
* TaskExecStdinWrite message larger than 100MiB (RESOURCE_EXHAUSTED at
|
|
49
|
-
* 104,857,600 bytes), so file payloads are split into 8MiB writeBytes()
|
|
50
|
-
* calls — the same per-chunk pattern writeStream() uses.
|
|
51
|
-
*/
|
|
52
|
-
declare const MODAL_STDIN_CHUNK_BYTES: number;
|
|
53
|
-
/**
|
|
54
|
-
* Typed error for Modal's hard 24h sandbox lifetime cap.
|
|
55
|
-
* Long-running sessions must persist progress with Evolve checkpoints and
|
|
56
|
-
* resume in a fresh sandbox instead of extending the timeout.
|
|
57
|
-
*/
|
|
58
|
-
declare class ModalSandboxLifetimeError extends Error {
|
|
59
|
-
readonly requestedTimeoutMs: number;
|
|
60
|
-
constructor(requestedTimeoutMs: number);
|
|
61
|
-
}
|
|
62
|
-
/** Throws ModalSandboxLifetimeError when the timeout exceeds Modal's 24h cap. */
|
|
63
|
-
declare function validateTimeout(timeoutMs: number): void;
|
|
64
|
-
/**
|
|
65
|
-
* Typed error for an idle timeout Modal could not act on. Both bounds are
|
|
66
|
-
* refusals rather than clamps: silently raising a zero, or lowering a value past
|
|
67
|
-
* the lifetime cap, would hand back a box that dies on a schedule the caller
|
|
68
|
-
* never asked for.
|
|
69
|
-
*/
|
|
70
|
-
declare class ModalIdleTimeoutError extends Error {
|
|
71
|
-
readonly requestedIdleTimeoutMs: number;
|
|
72
|
-
constructor(requestedIdleTimeoutMs: number, reason: string);
|
|
73
|
-
}
|
|
74
|
-
/**
|
|
75
|
-
* Evolve's idle bound -> Modal's create params, same shape as mapNetworkPolicy
|
|
76
|
-
* and mapResources: provider-neutral option in, Modal fragment out.
|
|
77
|
-
*
|
|
78
|
-
* ABSENT MEANS ABSENT. Modal's own default is no idle timer at all, so an unset
|
|
79
|
-
* option must spread to nothing — inventing a default here would start killing
|
|
80
|
-
* boxes that today live out their lifetime, for every caller who never asked.
|
|
81
|
-
*
|
|
82
|
-
* An idle timeout has to be a positive span, and one above the 24h lifetime cap
|
|
83
|
-
* can never fire because the sandbox is already gone. Both are caller mistakes,
|
|
84
|
-
* and both throw rather than clamp: silently raising a zero or lowering an
|
|
85
|
-
* over-cap value hands back a box that dies on a schedule nobody chose.
|
|
86
|
-
*/
|
|
87
|
-
declare function mapIdleTimeout(idleTimeoutMs?: number): {
|
|
88
|
-
idleTimeoutMs?: number;
|
|
89
|
-
};
|
|
90
|
-
/**
|
|
91
|
-
* Wrap a command with cwd + env handling and (when not root) an
|
|
92
|
-
* `su <user> -c` wrapper.
|
|
93
|
-
*
|
|
94
|
-
* Modal sandboxes run as root by default (ignoring the Dockerfile USER
|
|
95
|
-
* directive), but Claude CLI and other tools refuse certain operations when
|
|
96
|
-
* running as root.
|
|
97
|
-
*
|
|
98
|
-
* Uses `su <user> -c` instead of `sudo -u <user>` because Claude CLI's
|
|
99
|
-
* --dangerously-skip-permissions flag refuses to run when it detects sudo.
|
|
100
|
-
*
|
|
101
|
-
* Uses base64 encoding to avoid shell escaping issues with complex commands
|
|
102
|
-
* that contain quotes, special characters, etc. Env vars are inlined because
|
|
103
|
-
* su does not preserve the environment the way `sudo -E` does.
|
|
104
|
-
*/
|
|
105
|
-
declare function wrapCommand(command: string, user: string, cwd?: string, envs?: Record<string, string>): string[];
|
|
106
|
-
/**
|
|
107
|
-
* Typed error for sizing requests Modal's create() cannot enforce.
|
|
108
|
-
* The installed Modal JS SDK sizes cpu (cores) and memoryMiB at create time
|
|
109
|
-
* only — there is no disk-size parameter, so a requested disk size would be
|
|
110
|
-
* silently ignored. Per the provider law (reject what you cannot enforce,
|
|
111
|
-
* never silently ignore) it is refused loudly here.
|
|
112
|
-
*/
|
|
113
|
-
declare class ModalResourcesError extends Error {
|
|
114
|
-
constructor(message: string);
|
|
115
|
-
}
|
|
116
|
-
/**
|
|
117
|
-
* Map Evolve's provider-neutral resources (cpu cores, memory GiB, disk GiB)
|
|
118
|
-
* onto Modal's create() params (cpu cores, memoryMiB). Fractional GiB rounds
|
|
119
|
-
* UP so the sandbox never gets less memory than requested. `disk` throws
|
|
120
|
-
* ModalResourcesError — the SDK cannot express it.
|
|
121
|
-
*/
|
|
122
|
-
declare function mapResources(resources?: SandboxCreateOptions["resources"]): {
|
|
123
|
-
cpu: number;
|
|
124
|
-
memoryMiB: number;
|
|
125
|
-
};
|
|
126
|
-
/** Modal create() params derived from Evolve's provider-neutral network policy. */
|
|
127
|
-
interface ModalNetworkCreateParams {
|
|
128
|
-
blockNetwork?: boolean;
|
|
129
|
-
outboundCidrAllowlist?: string[];
|
|
130
|
-
outboundDomainAllowlist?: string[];
|
|
131
|
-
}
|
|
132
|
-
/** Why a network destination cannot be mapped onto Modal's allowlist. */
|
|
133
|
-
type ModalNetworkPolicyReason = "port-unsupported" | "invalid-ipv4";
|
|
134
|
-
/**
|
|
135
|
-
* Typed error for destinations Modal's allowlist cannot express.
|
|
136
|
-
*
|
|
137
|
-
* Modal's allowlist filters hosts (domain allowlist) and IPs/CIDRs (CIDR
|
|
138
|
-
* allowlist) only — it has no notion of a port, and an invalid IPv4/CIDR
|
|
139
|
-
* would be silently forwarded to the API. Both are rejected loudly here
|
|
140
|
-
* instead of weakening or mangling the sandbox's egress policy.
|
|
141
|
-
*/
|
|
142
|
-
declare class ModalNetworkPolicyError extends Error {
|
|
143
|
-
readonly reason: ModalNetworkPolicyReason;
|
|
144
|
-
/** The offending destination. */
|
|
145
|
-
readonly destination?: string;
|
|
146
|
-
constructor(reason: ModalNetworkPolicyReason, message: string, destination?: string);
|
|
147
|
-
}
|
|
148
|
-
/**
|
|
149
|
-
* Map Evolve's provider-neutral network policy onto Modal create() params.
|
|
150
|
-
*
|
|
151
|
-
* - outbound "open" (or no policy) → no restrictions
|
|
152
|
-
* - outbound "blocked", no allowlist → blockNetwork: true (drops all egress)
|
|
153
|
-
* - outbound "blocked" with allowlist → outboundDomainAllowlist (hostnames,
|
|
154
|
-
* wildcards like "*.example.com") + outboundCidrAllowlist (IPs/CIDRs; bare
|
|
155
|
-
* IPs get /32 or /128 appended). Both lists are always set because Modal
|
|
156
|
-
* treats an unset list as "allow all" — an empty array means "allow none"
|
|
157
|
-
* for that class of destination. Note: Modal's domain allowlist only admits
|
|
158
|
-
* TLS traffic on port 443; plaintext destinations must be listed as CIDRs.
|
|
159
|
-
*/
|
|
160
|
-
declare function mapNetworkPolicy(network?: SandboxCreateOptions["network"]): ModalNetworkCreateParams;
|
|
161
|
-
/** Container registry family for an image tag. */
|
|
162
|
-
type ImageRegistry = "aws-ecr" | "gcp-artifact-registry" | "registry";
|
|
163
|
-
/** Detect which Modal image constructor an image tag needs. */
|
|
164
|
-
declare function resolveImageRegistry(tag: string): ImageRegistry;
|
|
165
|
-
/**
|
|
166
|
-
* Build a SandboxInfo from a sandbox's tags. Modal exposes no metadata or
|
|
167
|
-
* public timestamps, so image and startedAt come from the tags stamped at
|
|
168
|
-
* create time; for sandboxes not created by this SDK they are empty strings
|
|
169
|
-
* (never fabricated). endAt is always undefined — Modal does not expose it.
|
|
170
18
|
*/
|
|
171
|
-
declare function buildSandboxInfo(sandboxId: string, tags: Record<string, string>, fallbackImage?: string): SandboxInfo;
|
|
172
19
|
/** Result of a completed sandbox command */
|
|
173
20
|
interface SandboxCommandResult {
|
|
174
21
|
exitCode: number;
|
|
@@ -246,83 +93,15 @@ interface SandboxCreateOptions {
|
|
|
246
93
|
image?: string;
|
|
247
94
|
envs?: Record<string, string>;
|
|
248
95
|
metadata?: Record<string, string>;
|
|
249
|
-
/** Sandbox lifetime in ms. Modal hard-caps lifetime at 24h (MODAL_MAX_LIFETIME_MS). */
|
|
250
96
|
timeoutMs?: number;
|
|
251
|
-
/**
|
|
252
|
-
* Terminate the sandbox after this long with nothing running in it — the
|
|
253
|
-
* bound that reclaims a box whose client died, without waiting out the whole
|
|
254
|
-
* lifetime. Modal is the only provider with both clocks.
|
|
255
|
-
*
|
|
256
|
-
* OMITTED BY DEFAULT: Modal runs no idle timer unless asked. Modal counts a
|
|
257
|
-
* sandbox active while an exec is running, while its stdin is being written,
|
|
258
|
-
* or while a tunnel connection is open — file operations are not named in
|
|
259
|
-
* that list, and this adapter is safe only because it routes reads and writes
|
|
260
|
-
* through exec (`cat` / `cat >`). A future native filesystem path would need
|
|
261
|
-
* this re-checked.
|
|
262
|
-
*/
|
|
263
|
-
idleTimeoutMs?: number;
|
|
264
97
|
workingDirectory?: string;
|
|
265
|
-
/**
|
|
266
|
-
* Per-sandbox compute sizing: cpu in cores, memory in GiB — mapped to
|
|
267
|
-
* Modal's create-time cpu / memoryMiB requests (defaults when omitted:
|
|
268
|
-
* 4 cores / 4 GiB). `disk` is REJECTED with ModalResourcesError: the Modal
|
|
269
|
-
* JS SDK exposes no disk-size parameter, so a specific disk size cannot be
|
|
270
|
-
* enforced (containers get Modal's default disk quota).
|
|
271
|
-
*/
|
|
272
|
-
resources?: {
|
|
273
|
-
cpu?: number;
|
|
274
|
-
memory?: number;
|
|
275
|
-
disk?: number;
|
|
276
|
-
};
|
|
277
|
-
/**
|
|
278
|
-
* Provider-neutral outbound network policy, enforced by Modal's network
|
|
279
|
-
* stack. "blocked" with no allowedDestinations drops all egress; with
|
|
280
|
-
* allowedDestinations, hostnames go to Modal's domain allowlist (TLS/443
|
|
281
|
-
* only) and IPs/CIDRs to the CIDR allowlist.
|
|
282
|
-
*/
|
|
283
|
-
network?: {
|
|
284
|
-
outbound: "open" | "blocked";
|
|
285
|
-
allowedDestinations?: string[];
|
|
286
|
-
};
|
|
287
|
-
/**
|
|
288
|
-
* Run all commands and file operations as this user (default "user"),
|
|
289
|
-
* enforced via an `su <user> -c` wrapper since Modal executes everything as
|
|
290
|
-
* root. Pass "root" to run directly as root with no wrapper.
|
|
291
|
-
*/
|
|
292
|
-
user?: string;
|
|
293
|
-
/** Home directory used by the SDK for agent config paths; not consumed by the provider. */
|
|
294
|
-
homeDir?: string;
|
|
295
98
|
}
|
|
296
99
|
/** Options for listing sandboxes */
|
|
297
100
|
interface SandboxListOptions {
|
|
298
|
-
/** Modal has no paused state; filters that exclude "running" match nothing. */
|
|
299
101
|
state?: ("running" | "paused")[];
|
|
300
102
|
metadata?: Record<string, string>;
|
|
301
103
|
limit?: number;
|
|
302
104
|
}
|
|
303
|
-
/**
|
|
304
|
-
* A COMPLETE (or admittedly incomplete) enumeration of the app's fleet.
|
|
305
|
-
*
|
|
306
|
-
* `complete` is the load-bearing field. Callers that need a whole fleet —
|
|
307
|
-
* orphan sweeps, lifecycle reconciliation — read a sandbox's ABSENCE from the
|
|
308
|
-
* list as evidence it is gone, so a truncated walk and a small fleet must never
|
|
309
|
-
* be the same answer. That includes a walk stopped by the caller's own `limit`:
|
|
310
|
-
* "you asked for ten and there are more" is a truncated fleet.
|
|
311
|
-
*/
|
|
312
|
-
interface SandboxListPage {
|
|
313
|
-
sandboxes: SandboxInfo[];
|
|
314
|
-
complete: boolean;
|
|
315
|
-
pagesFetched: number;
|
|
316
|
-
error?: string;
|
|
317
|
-
}
|
|
318
|
-
/**
|
|
319
|
-
* Sandboxes a single enumeration will walk before it gives up and reports
|
|
320
|
-
* itself incomplete. Modal's list is an async generator with no page size we
|
|
321
|
-
* control, so the ceiling is counted in SANDBOXES rather than pages — same
|
|
322
|
-
* purpose as the other providers' page caps: never return a short list that
|
|
323
|
-
* reads like a whole one.
|
|
324
|
-
*/
|
|
325
|
-
declare const MODAL_MAX_LIST_SANDBOXES = 10000;
|
|
326
105
|
/** Command execution capabilities */
|
|
327
106
|
interface SandboxCommands {
|
|
328
107
|
/** Run command and wait for completion */
|
|
@@ -353,8 +132,6 @@ interface SandboxFiles {
|
|
|
353
132
|
readStream(path: string): Promise<ReadableStream<Uint8Array>>;
|
|
354
133
|
/** Write from stream */
|
|
355
134
|
writeStream(path: string, stream: ReadableStream<Uint8Array>): Promise<void>;
|
|
356
|
-
/** Upload a local file by path, streamed off disk (never buffered whole) */
|
|
357
|
-
writeFromPath(sandboxPath: string, localPath: string): Promise<void>;
|
|
358
135
|
/** Get pre-signed upload URL for large files (expiration in seconds) */
|
|
359
136
|
uploadUrl(path: string, expiresInSeconds?: number): Promise<string>;
|
|
360
137
|
/** Get pre-signed download URL for large files (expiration in seconds) */
|
|
@@ -392,17 +169,12 @@ interface SandboxInstance {
|
|
|
392
169
|
interface SandboxProvider {
|
|
393
170
|
/** Provider type identifier */
|
|
394
171
|
readonly providerType: string;
|
|
395
|
-
/** Human-readable provider name for logging */
|
|
396
|
-
readonly name?: string;
|
|
397
172
|
/** Create new sandbox */
|
|
398
173
|
create(options: SandboxCreateOptions): Promise<SandboxInstance>;
|
|
399
174
|
/** Connect to existing sandbox */
|
|
400
175
|
connect(sandboxId: string, timeoutMs?: number): Promise<SandboxInstance>;
|
|
401
176
|
/** List sandboxes (first page only, up to limit) */
|
|
402
|
-
/** List sandboxes, walking the whole app. `limit` bounds items returned. */
|
|
403
177
|
list(options?: SandboxListOptions): Promise<SandboxInfo[]>;
|
|
404
|
-
/** The same enumeration for fleet bookkeeping: never throws, reports completeness. */
|
|
405
|
-
listAll(options?: SandboxListOptions): Promise<SandboxListPage>;
|
|
406
178
|
}
|
|
407
179
|
interface ModalConfig {
|
|
408
180
|
/** Modal app name. Default: "evolve-sandbox" */
|
|
@@ -415,15 +187,8 @@ interface ModalConfig {
|
|
|
415
187
|
tokenSecret?: string;
|
|
416
188
|
/** Modal API endpoint. Default: https://api.modal.com:443 */
|
|
417
189
|
endpoint?: string;
|
|
418
|
-
/** Docker image name (default: 'evolve-all
|
|
190
|
+
/** Docker image name (default: 'evolve-all'). Resolved through IMAGE_MAP or used as-is for custom images. */
|
|
419
191
|
imageName?: string;
|
|
420
|
-
/**
|
|
421
|
-
* Name of a Modal Secret holding registry credentials for private images.
|
|
422
|
-
* Required for AWS ECR (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
|
|
423
|
-
* AWS_REGION with read-only ECR IAM) and GCP Artifact Registry; optional
|
|
424
|
-
* for private Docker Hub images. Create one at https://modal.com/secrets
|
|
425
|
-
*/
|
|
426
|
-
imageSecretName?: string;
|
|
427
192
|
}
|
|
428
193
|
/** Internal resolved config with required credentials */
|
|
429
194
|
interface ResolvedModalConfig {
|
|
@@ -433,64 +198,6 @@ interface ResolvedModalConfig {
|
|
|
433
198
|
defaultTimeoutMs?: number;
|
|
434
199
|
endpoint?: string;
|
|
435
200
|
imageName?: string;
|
|
436
|
-
imageSecretName?: string;
|
|
437
|
-
}
|
|
438
|
-
declare class ModalCommands implements SandboxCommands {
|
|
439
|
-
private sandbox;
|
|
440
|
-
private user;
|
|
441
|
-
constructor(sandbox: Sandbox, user: string);
|
|
442
|
-
run(command: string, options?: SandboxRunOptions): Promise<SandboxCommandResult>;
|
|
443
|
-
spawn(command: string, options?: SandboxSpawnOptions): Promise<SandboxCommandHandle>;
|
|
444
|
-
list(): Promise<ProcessInfo[]>;
|
|
445
|
-
connect(_processId: string, _options?: SandboxConnectOptions): Promise<SandboxCommandHandle>;
|
|
446
|
-
sendStdin(_processId: string, _data: string): Promise<void>;
|
|
447
|
-
kill(processId: string): Promise<boolean>;
|
|
448
|
-
/**
|
|
449
|
-
* Accumulate stdout/stderr using for-await pattern (more reliable with Modal streams).
|
|
450
|
-
* Based on vibekit's approach which works correctly with Modal SDK.
|
|
451
|
-
*/
|
|
452
|
-
private accumulateStreams;
|
|
453
|
-
}
|
|
454
|
-
declare class ModalFiles implements SandboxFiles {
|
|
455
|
-
private sandbox;
|
|
456
|
-
private user;
|
|
457
|
-
constructor(sandbox: Sandbox, user: string);
|
|
458
|
-
/**
|
|
459
|
-
* Chown a path to the sandbox user so agent CLIs (running via the su
|
|
460
|
-
* wrapper) can access files created by root-level exec. No-op when the
|
|
461
|
-
* sandbox user is root.
|
|
462
|
-
*/
|
|
463
|
-
private chownToUser;
|
|
464
|
-
/**
|
|
465
|
-
* Write a payload to a process's stdin in MODAL_STDIN_CHUNK_BYTES slices.
|
|
466
|
-
* Each writeBytes() call becomes one gRPC TaskExecStdinWrite message and
|
|
467
|
-
* Modal rejects messages over 100MiB, so large files must be chunked
|
|
468
|
-
* (multi-hundred-MB payloads are common).
|
|
469
|
-
*/
|
|
470
|
-
private writeStdinChunked;
|
|
471
|
-
read(path: string): Promise<string | Uint8Array>;
|
|
472
|
-
write(path: string, content: string | Buffer | ArrayBuffer | Uint8Array): Promise<void>;
|
|
473
|
-
writeBatch(files: Array<{
|
|
474
|
-
path: string;
|
|
475
|
-
data: string | Buffer | ArrayBuffer | Uint8Array;
|
|
476
|
-
}>): Promise<void>;
|
|
477
|
-
makeDir(path: string): Promise<void>;
|
|
478
|
-
exists(path: string): Promise<boolean>;
|
|
479
|
-
list(path: string): Promise<FileInfo[]>;
|
|
480
|
-
remove(path: string): Promise<void>;
|
|
481
|
-
rename(oldPath: string, newPath: string): Promise<void>;
|
|
482
|
-
readStream(path: string): Promise<ReadableStream<Uint8Array>>;
|
|
483
|
-
writeStream(path: string, stream: ReadableStream<Uint8Array>): Promise<void>;
|
|
484
|
-
/**
|
|
485
|
-
* Upload a local file by PATH, chunk by chunk into the same `cat >` sink
|
|
486
|
-
* writeStream() uses — so peak memory is one chunk rather than the whole
|
|
487
|
-
* file, which is what makes a large artifact safe under concurrency.
|
|
488
|
-
*/
|
|
489
|
-
writeFromPath(sandboxPath: string, localPath: string): Promise<void>;
|
|
490
|
-
uploadUrl(_path: string, _expiresInSeconds?: number): Promise<string>;
|
|
491
|
-
downloadUrl(_path: string, _expiresInSeconds?: number): Promise<string>;
|
|
492
|
-
watchDir(_path: string, _onEvent: (event: FilesystemEvent) => void | Promise<void>, _options?: WatchOptions): Promise<WatchHandle>;
|
|
493
|
-
private toBuffer;
|
|
494
201
|
}
|
|
495
202
|
declare class ModalProvider implements SandboxProvider {
|
|
496
203
|
readonly providerType: "modal";
|
|
@@ -499,103 +206,13 @@ declare class ModalProvider implements SandboxProvider {
|
|
|
499
206
|
private readonly appName;
|
|
500
207
|
private readonly defaultTimeoutMs;
|
|
501
208
|
private readonly imageName;
|
|
502
|
-
private readonly imageSecretName?;
|
|
503
209
|
private _app;
|
|
504
|
-
/**
|
|
505
|
-
* Sandbox user configured at create time, reapplied on connect() so the su
|
|
506
|
-
* wrapper keeps targeting the same account. In-memory only: a connect()
|
|
507
|
-
* from a fresh process falls back to the default "user" account — callers
|
|
508
|
-
* reconnecting across processes must recreate the provider and sandbox with
|
|
509
|
-
* the same user, or operations on user-owned files fail loudly.
|
|
510
|
-
*/
|
|
511
|
-
private readonly sandboxUsers;
|
|
512
210
|
constructor(config: ResolvedModalConfig);
|
|
513
211
|
private getApp;
|
|
514
|
-
/**
|
|
515
|
-
* Build a Modal Image for the resolved tag, routing private registries
|
|
516
|
-
* (AWS ECR, GCP Artifact Registry) through the configured Modal Secret.
|
|
517
|
-
*/
|
|
518
|
-
private resolveImage;
|
|
519
212
|
create(options: SandboxCreateOptions): Promise<SandboxInstance>;
|
|
520
213
|
connect(sandboxId: string, _timeoutMs?: number): Promise<SandboxInstance>;
|
|
521
|
-
|
|
522
|
-
* List sandboxes, walking the whole app.
|
|
523
|
-
*
|
|
524
|
-
* This used to stop at a hardcoded default of 100 regardless of fleet size,
|
|
525
|
-
* which silently truncated any app with more — and said nothing about it
|
|
526
|
-
* while the shared SandboxProvider interface promised exhaustive listing.
|
|
527
|
-
* `limit` still bounds the sandboxes RETURNED, so a caller wanting one cheap
|
|
528
|
-
* sample asks for one; without it the answer is the whole app.
|
|
529
|
-
*
|
|
530
|
-
* The O(N)-round-trips warning below is unchanged and is the reason `limit`
|
|
531
|
-
* matters here more than on the other providers.
|
|
532
|
-
*/
|
|
533
|
-
list(options?: SandboxListOptions): Promise<SandboxInfo[]>;
|
|
534
|
-
/**
|
|
535
|
-
* The fleet-bookkeeping enumeration: same walk, never throws.
|
|
536
|
-
*
|
|
537
|
-
* Modal has no lifecycle webhooks, so absence from a list is the ONLY
|
|
538
|
-
* termination signal either lane gets — which makes the difference between
|
|
539
|
-
* "the app is empty" and "the enumeration stopped early" the difference
|
|
540
|
-
* between a quiet fleet and one about to be reclaimed.
|
|
541
|
-
*
|
|
542
|
-
* NOTE the divergence from `listSandboxIds` below, which returns an EMPTY set
|
|
543
|
-
* on failure on the grounds that partial results are worse than none for a
|
|
544
|
-
* terminal-state decision. This one returns what it saw alongside
|
|
545
|
-
* `complete: false`. Both are safe because `complete` is what callers branch
|
|
546
|
-
* on, and the shared type documents the choice; do not align one to the other
|
|
547
|
-
* without deciding which rule you want.
|
|
548
|
-
*/
|
|
549
|
-
listAll(options?: SandboxListOptions): Promise<SandboxListPage>;
|
|
550
|
-
private walk;
|
|
551
|
-
/**
|
|
552
|
-
* Live sandbox ids for the whole app, in ONE streamed call and O(1) round
|
|
553
|
-
* trips — the fleet-bookkeeping counterpart to `list()`.
|
|
554
|
-
*
|
|
555
|
-
* Exists because `list()` cannot be made cheap without dropping metadata from
|
|
556
|
-
* its contract: it owes callers a populated `SandboxInfo.metadata`, and Modal
|
|
557
|
-
* only serves tags per sandbox. Anything that just needs "which ids are
|
|
558
|
-
* alive" — lifecycle polling, orphan sweeps, reconciliation — uses this and
|
|
559
|
-
* pays one request no matter how large the fleet is.
|
|
560
|
-
*
|
|
561
|
-
* `complete` is the load-bearing field, not a nicety: absence from this list
|
|
562
|
-
* is what callers read as "terminated", so a truncated or errored enumeration
|
|
563
|
-
* MUST NOT be mistaken for an empty fleet. A caller that sees complete=false
|
|
564
|
-
* has to leave rows alone rather than mass-marking live sandboxes dead.
|
|
565
|
-
*/
|
|
566
|
-
listSandboxIds(): Promise<{
|
|
567
|
-
ids: Set<string>;
|
|
568
|
-
complete: boolean;
|
|
569
|
-
}>;
|
|
214
|
+
list(_options?: SandboxListOptions): Promise<SandboxInfo[]>;
|
|
570
215
|
}
|
|
571
|
-
/** The streamed sandbox surface this walk needs — Modal's list() satisfies it. */
|
|
572
|
-
interface ModalSandboxStream {
|
|
573
|
-
sandboxId: string;
|
|
574
|
-
getTags(): Promise<Record<string, string>>;
|
|
575
|
-
}
|
|
576
|
-
/**
|
|
577
|
-
* Drain Modal's sandbox generator into one answer, with an honest completeness
|
|
578
|
-
* verdict.
|
|
579
|
-
*
|
|
580
|
-
* Separate from the provider because everything worth getting wrong lives here
|
|
581
|
-
* and none of it needs a gRPC connection: the difference between "the caller
|
|
582
|
-
* asked for ten" and "the app ran out", the ceiling that stops an unbounded
|
|
583
|
-
* walk, and the rule that a failure mid-walk yields what it saw marked
|
|
584
|
-
* INCOMPLETE rather than an exception or a short complete list.
|
|
585
|
-
*
|
|
586
|
-
* COST WARNING — this loop is O(N) ROUND TRIPS, not O(1). `list()` itself is one
|
|
587
|
-
* streamed call, but `getTags()` is a separate gRPC request per sandbox
|
|
588
|
-
* (`sandboxTagsGet`), so listing N sandboxes costs N+1 calls. That is fine for a
|
|
589
|
-
* user listing their handful of boxes with metadata, and NOT fine for fleet-wide
|
|
590
|
-
* bookkeeping: anything that only needs to know WHICH ids are alive must use
|
|
591
|
-
* `listSandboxIds`, never this. Please do not "optimize" by reintroducing tag
|
|
592
|
-
* reads into those paths.
|
|
593
|
-
*
|
|
594
|
-
* Exported for its test (`_testCollectSandboxes`).
|
|
595
|
-
*/
|
|
596
|
-
declare function collectSandboxes(iterate: () => AsyncIterable<ModalSandboxStream>, wanted?: number): Promise<SandboxListPage & {
|
|
597
|
-
stoppedAtLimit: boolean;
|
|
598
|
-
}>;
|
|
599
216
|
/**
|
|
600
217
|
* Create Modal sandbox provider.
|
|
601
218
|
*
|
|
@@ -605,14 +222,5 @@ declare function collectSandboxes(iterate: () => AsyncIterable<ModalSandboxStrea
|
|
|
605
222
|
* @see https://github.com/evolving-machines-lab/evolve/issues/8
|
|
606
223
|
*/
|
|
607
224
|
declare function createModalProvider(config?: ModalConfig): SandboxProvider;
|
|
608
|
-
declare const _testWrapCommand: typeof wrapCommand;
|
|
609
|
-
declare const _testImageMap: Record<string, string>;
|
|
610
|
-
declare const _testMapNetworkPolicy: typeof mapNetworkPolicy;
|
|
611
|
-
declare const _testMapResources: typeof mapResources;
|
|
612
|
-
declare const _testResolveImageRegistry: typeof resolveImageRegistry;
|
|
613
|
-
declare const _testBuildSandboxInfo: typeof buildSandboxInfo;
|
|
614
|
-
declare const _testCollectSandboxes: typeof collectSandboxes;
|
|
615
|
-
declare const _testValidateTimeout: typeof validateTimeout;
|
|
616
|
-
declare const _testMapIdleTimeout: typeof mapIdleTimeout;
|
|
617
225
|
|
|
618
|
-
export {
|
|
226
|
+
export { type FileInfo, type FilesystemEvent, type ModalConfig, ModalProvider, type ProcessInfo, type SandboxCommandHandle, type SandboxCommandResult, type SandboxCommands, type SandboxConnectOptions, type SandboxCreateOptions, type SandboxFiles, type SandboxInfo, type SandboxInstance, type SandboxListOptions, type SandboxProvider, type SandboxRunOptions, type SandboxSpawnOptions, type WatchHandle, type WatchOptions, createModalProvider };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,20 +1,7 @@
|
|
|
1
|
-
import { Sandbox } from 'modal';
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
* GENERATED — DO NOT EDIT. `npm run generate:image-version` (repo root)
|
|
5
|
-
* rewrites this file from the evolve-all image build inputs under
|
|
6
|
-
* assets/docker/ (see assets/docker/image-digest.ts for the derivation).
|
|
7
|
-
* The value is content-addressed: same inputs → same tag, any input
|
|
8
|
-
* change → a new tag. The coherence test in
|
|
9
|
-
* packages/daytona/tests/unit/daytona-image-version.test.ts fails the
|
|
10
|
-
* suite whenever this checked-in copy is stale.
|
|
11
|
-
*/
|
|
12
|
-
declare const EVOLVE_IMAGE_VERSION = "c-6cd57962a3d9";
|
|
13
|
-
|
|
14
1
|
/**
|
|
15
2
|
* Modal Sandbox Provider - Clean Architecture
|
|
16
3
|
*
|
|
17
|
-
* @requires modal >= 0.
|
|
4
|
+
* @requires modal >= 0.3.0
|
|
18
5
|
* @requires Node.js >= 18 (for ReadableStream support)
|
|
19
6
|
*
|
|
20
7
|
* Design principles:
|
|
@@ -26,149 +13,9 @@ declare const EVOLVE_IMAGE_VERSION = "c-6cd57962a3d9";
|
|
|
26
13
|
*
|
|
27
14
|
* Modal-specific notes:
|
|
28
15
|
* - No native file APIs - uses exec() with stdin/stdout
|
|
29
|
-
* - pause() not supported - throws error
|
|
16
|
+
* - pause() not supported - throws error
|
|
30
17
|
* - Requires app context for sandbox creation
|
|
31
|
-
* - Hard 24h sandbox lifetime cap (ModalSandboxLifetimeError when exceeded)
|
|
32
|
-
* - Everything executes as root inside the sandbox; the `user` option is
|
|
33
|
-
* enforced through an `su <user> -c` wrapper (default user: "user")
|
|
34
|
-
* - Network policy maps to Modal's blockNetwork / outboundDomainAllowlist /
|
|
35
|
-
* outboundCidrAllowlist (domain allowlist admits TLS on port 443 only —
|
|
36
|
-
* plaintext destinations must be listed as IPs/CIDRs)
|
|
37
|
-
* - Modal exposes no metadata or public timestamps on sandboxes; both are
|
|
38
|
-
* stamped into sandbox tags at create time and read back via getTags()
|
|
39
|
-
*/
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
* Modal's hard cap on sandbox lifetime (24 hours).
|
|
43
|
-
* Requests beyond this throw ModalSandboxLifetimeError.
|
|
44
|
-
*/
|
|
45
|
-
declare const MODAL_MAX_LIFETIME_MS: number;
|
|
46
|
-
/**
|
|
47
|
-
* Chunk size for stdin uploads. Modal's gRPC transport rejects any single
|
|
48
|
-
* TaskExecStdinWrite message larger than 100MiB (RESOURCE_EXHAUSTED at
|
|
49
|
-
* 104,857,600 bytes), so file payloads are split into 8MiB writeBytes()
|
|
50
|
-
* calls — the same per-chunk pattern writeStream() uses.
|
|
51
|
-
*/
|
|
52
|
-
declare const MODAL_STDIN_CHUNK_BYTES: number;
|
|
53
|
-
/**
|
|
54
|
-
* Typed error for Modal's hard 24h sandbox lifetime cap.
|
|
55
|
-
* Long-running sessions must persist progress with Evolve checkpoints and
|
|
56
|
-
* resume in a fresh sandbox instead of extending the timeout.
|
|
57
|
-
*/
|
|
58
|
-
declare class ModalSandboxLifetimeError extends Error {
|
|
59
|
-
readonly requestedTimeoutMs: number;
|
|
60
|
-
constructor(requestedTimeoutMs: number);
|
|
61
|
-
}
|
|
62
|
-
/** Throws ModalSandboxLifetimeError when the timeout exceeds Modal's 24h cap. */
|
|
63
|
-
declare function validateTimeout(timeoutMs: number): void;
|
|
64
|
-
/**
|
|
65
|
-
* Typed error for an idle timeout Modal could not act on. Both bounds are
|
|
66
|
-
* refusals rather than clamps: silently raising a zero, or lowering a value past
|
|
67
|
-
* the lifetime cap, would hand back a box that dies on a schedule the caller
|
|
68
|
-
* never asked for.
|
|
69
|
-
*/
|
|
70
|
-
declare class ModalIdleTimeoutError extends Error {
|
|
71
|
-
readonly requestedIdleTimeoutMs: number;
|
|
72
|
-
constructor(requestedIdleTimeoutMs: number, reason: string);
|
|
73
|
-
}
|
|
74
|
-
/**
|
|
75
|
-
* Evolve's idle bound -> Modal's create params, same shape as mapNetworkPolicy
|
|
76
|
-
* and mapResources: provider-neutral option in, Modal fragment out.
|
|
77
|
-
*
|
|
78
|
-
* ABSENT MEANS ABSENT. Modal's own default is no idle timer at all, so an unset
|
|
79
|
-
* option must spread to nothing — inventing a default here would start killing
|
|
80
|
-
* boxes that today live out their lifetime, for every caller who never asked.
|
|
81
|
-
*
|
|
82
|
-
* An idle timeout has to be a positive span, and one above the 24h lifetime cap
|
|
83
|
-
* can never fire because the sandbox is already gone. Both are caller mistakes,
|
|
84
|
-
* and both throw rather than clamp: silently raising a zero or lowering an
|
|
85
|
-
* over-cap value hands back a box that dies on a schedule nobody chose.
|
|
86
|
-
*/
|
|
87
|
-
declare function mapIdleTimeout(idleTimeoutMs?: number): {
|
|
88
|
-
idleTimeoutMs?: number;
|
|
89
|
-
};
|
|
90
|
-
/**
|
|
91
|
-
* Wrap a command with cwd + env handling and (when not root) an
|
|
92
|
-
* `su <user> -c` wrapper.
|
|
93
|
-
*
|
|
94
|
-
* Modal sandboxes run as root by default (ignoring the Dockerfile USER
|
|
95
|
-
* directive), but Claude CLI and other tools refuse certain operations when
|
|
96
|
-
* running as root.
|
|
97
|
-
*
|
|
98
|
-
* Uses `su <user> -c` instead of `sudo -u <user>` because Claude CLI's
|
|
99
|
-
* --dangerously-skip-permissions flag refuses to run when it detects sudo.
|
|
100
|
-
*
|
|
101
|
-
* Uses base64 encoding to avoid shell escaping issues with complex commands
|
|
102
|
-
* that contain quotes, special characters, etc. Env vars are inlined because
|
|
103
|
-
* su does not preserve the environment the way `sudo -E` does.
|
|
104
|
-
*/
|
|
105
|
-
declare function wrapCommand(command: string, user: string, cwd?: string, envs?: Record<string, string>): string[];
|
|
106
|
-
/**
|
|
107
|
-
* Typed error for sizing requests Modal's create() cannot enforce.
|
|
108
|
-
* The installed Modal JS SDK sizes cpu (cores) and memoryMiB at create time
|
|
109
|
-
* only — there is no disk-size parameter, so a requested disk size would be
|
|
110
|
-
* silently ignored. Per the provider law (reject what you cannot enforce,
|
|
111
|
-
* never silently ignore) it is refused loudly here.
|
|
112
|
-
*/
|
|
113
|
-
declare class ModalResourcesError extends Error {
|
|
114
|
-
constructor(message: string);
|
|
115
|
-
}
|
|
116
|
-
/**
|
|
117
|
-
* Map Evolve's provider-neutral resources (cpu cores, memory GiB, disk GiB)
|
|
118
|
-
* onto Modal's create() params (cpu cores, memoryMiB). Fractional GiB rounds
|
|
119
|
-
* UP so the sandbox never gets less memory than requested. `disk` throws
|
|
120
|
-
* ModalResourcesError — the SDK cannot express it.
|
|
121
|
-
*/
|
|
122
|
-
declare function mapResources(resources?: SandboxCreateOptions["resources"]): {
|
|
123
|
-
cpu: number;
|
|
124
|
-
memoryMiB: number;
|
|
125
|
-
};
|
|
126
|
-
/** Modal create() params derived from Evolve's provider-neutral network policy. */
|
|
127
|
-
interface ModalNetworkCreateParams {
|
|
128
|
-
blockNetwork?: boolean;
|
|
129
|
-
outboundCidrAllowlist?: string[];
|
|
130
|
-
outboundDomainAllowlist?: string[];
|
|
131
|
-
}
|
|
132
|
-
/** Why a network destination cannot be mapped onto Modal's allowlist. */
|
|
133
|
-
type ModalNetworkPolicyReason = "port-unsupported" | "invalid-ipv4";
|
|
134
|
-
/**
|
|
135
|
-
* Typed error for destinations Modal's allowlist cannot express.
|
|
136
|
-
*
|
|
137
|
-
* Modal's allowlist filters hosts (domain allowlist) and IPs/CIDRs (CIDR
|
|
138
|
-
* allowlist) only — it has no notion of a port, and an invalid IPv4/CIDR
|
|
139
|
-
* would be silently forwarded to the API. Both are rejected loudly here
|
|
140
|
-
* instead of weakening or mangling the sandbox's egress policy.
|
|
141
|
-
*/
|
|
142
|
-
declare class ModalNetworkPolicyError extends Error {
|
|
143
|
-
readonly reason: ModalNetworkPolicyReason;
|
|
144
|
-
/** The offending destination. */
|
|
145
|
-
readonly destination?: string;
|
|
146
|
-
constructor(reason: ModalNetworkPolicyReason, message: string, destination?: string);
|
|
147
|
-
}
|
|
148
|
-
/**
|
|
149
|
-
* Map Evolve's provider-neutral network policy onto Modal create() params.
|
|
150
|
-
*
|
|
151
|
-
* - outbound "open" (or no policy) → no restrictions
|
|
152
|
-
* - outbound "blocked", no allowlist → blockNetwork: true (drops all egress)
|
|
153
|
-
* - outbound "blocked" with allowlist → outboundDomainAllowlist (hostnames,
|
|
154
|
-
* wildcards like "*.example.com") + outboundCidrAllowlist (IPs/CIDRs; bare
|
|
155
|
-
* IPs get /32 or /128 appended). Both lists are always set because Modal
|
|
156
|
-
* treats an unset list as "allow all" — an empty array means "allow none"
|
|
157
|
-
* for that class of destination. Note: Modal's domain allowlist only admits
|
|
158
|
-
* TLS traffic on port 443; plaintext destinations must be listed as CIDRs.
|
|
159
|
-
*/
|
|
160
|
-
declare function mapNetworkPolicy(network?: SandboxCreateOptions["network"]): ModalNetworkCreateParams;
|
|
161
|
-
/** Container registry family for an image tag. */
|
|
162
|
-
type ImageRegistry = "aws-ecr" | "gcp-artifact-registry" | "registry";
|
|
163
|
-
/** Detect which Modal image constructor an image tag needs. */
|
|
164
|
-
declare function resolveImageRegistry(tag: string): ImageRegistry;
|
|
165
|
-
/**
|
|
166
|
-
* Build a SandboxInfo from a sandbox's tags. Modal exposes no metadata or
|
|
167
|
-
* public timestamps, so image and startedAt come from the tags stamped at
|
|
168
|
-
* create time; for sandboxes not created by this SDK they are empty strings
|
|
169
|
-
* (never fabricated). endAt is always undefined — Modal does not expose it.
|
|
170
18
|
*/
|
|
171
|
-
declare function buildSandboxInfo(sandboxId: string, tags: Record<string, string>, fallbackImage?: string): SandboxInfo;
|
|
172
19
|
/** Result of a completed sandbox command */
|
|
173
20
|
interface SandboxCommandResult {
|
|
174
21
|
exitCode: number;
|
|
@@ -246,83 +93,15 @@ interface SandboxCreateOptions {
|
|
|
246
93
|
image?: string;
|
|
247
94
|
envs?: Record<string, string>;
|
|
248
95
|
metadata?: Record<string, string>;
|
|
249
|
-
/** Sandbox lifetime in ms. Modal hard-caps lifetime at 24h (MODAL_MAX_LIFETIME_MS). */
|
|
250
96
|
timeoutMs?: number;
|
|
251
|
-
/**
|
|
252
|
-
* Terminate the sandbox after this long with nothing running in it — the
|
|
253
|
-
* bound that reclaims a box whose client died, without waiting out the whole
|
|
254
|
-
* lifetime. Modal is the only provider with both clocks.
|
|
255
|
-
*
|
|
256
|
-
* OMITTED BY DEFAULT: Modal runs no idle timer unless asked. Modal counts a
|
|
257
|
-
* sandbox active while an exec is running, while its stdin is being written,
|
|
258
|
-
* or while a tunnel connection is open — file operations are not named in
|
|
259
|
-
* that list, and this adapter is safe only because it routes reads and writes
|
|
260
|
-
* through exec (`cat` / `cat >`). A future native filesystem path would need
|
|
261
|
-
* this re-checked.
|
|
262
|
-
*/
|
|
263
|
-
idleTimeoutMs?: number;
|
|
264
97
|
workingDirectory?: string;
|
|
265
|
-
/**
|
|
266
|
-
* Per-sandbox compute sizing: cpu in cores, memory in GiB — mapped to
|
|
267
|
-
* Modal's create-time cpu / memoryMiB requests (defaults when omitted:
|
|
268
|
-
* 4 cores / 4 GiB). `disk` is REJECTED with ModalResourcesError: the Modal
|
|
269
|
-
* JS SDK exposes no disk-size parameter, so a specific disk size cannot be
|
|
270
|
-
* enforced (containers get Modal's default disk quota).
|
|
271
|
-
*/
|
|
272
|
-
resources?: {
|
|
273
|
-
cpu?: number;
|
|
274
|
-
memory?: number;
|
|
275
|
-
disk?: number;
|
|
276
|
-
};
|
|
277
|
-
/**
|
|
278
|
-
* Provider-neutral outbound network policy, enforced by Modal's network
|
|
279
|
-
* stack. "blocked" with no allowedDestinations drops all egress; with
|
|
280
|
-
* allowedDestinations, hostnames go to Modal's domain allowlist (TLS/443
|
|
281
|
-
* only) and IPs/CIDRs to the CIDR allowlist.
|
|
282
|
-
*/
|
|
283
|
-
network?: {
|
|
284
|
-
outbound: "open" | "blocked";
|
|
285
|
-
allowedDestinations?: string[];
|
|
286
|
-
};
|
|
287
|
-
/**
|
|
288
|
-
* Run all commands and file operations as this user (default "user"),
|
|
289
|
-
* enforced via an `su <user> -c` wrapper since Modal executes everything as
|
|
290
|
-
* root. Pass "root" to run directly as root with no wrapper.
|
|
291
|
-
*/
|
|
292
|
-
user?: string;
|
|
293
|
-
/** Home directory used by the SDK for agent config paths; not consumed by the provider. */
|
|
294
|
-
homeDir?: string;
|
|
295
98
|
}
|
|
296
99
|
/** Options for listing sandboxes */
|
|
297
100
|
interface SandboxListOptions {
|
|
298
|
-
/** Modal has no paused state; filters that exclude "running" match nothing. */
|
|
299
101
|
state?: ("running" | "paused")[];
|
|
300
102
|
metadata?: Record<string, string>;
|
|
301
103
|
limit?: number;
|
|
302
104
|
}
|
|
303
|
-
/**
|
|
304
|
-
* A COMPLETE (or admittedly incomplete) enumeration of the app's fleet.
|
|
305
|
-
*
|
|
306
|
-
* `complete` is the load-bearing field. Callers that need a whole fleet —
|
|
307
|
-
* orphan sweeps, lifecycle reconciliation — read a sandbox's ABSENCE from the
|
|
308
|
-
* list as evidence it is gone, so a truncated walk and a small fleet must never
|
|
309
|
-
* be the same answer. That includes a walk stopped by the caller's own `limit`:
|
|
310
|
-
* "you asked for ten and there are more" is a truncated fleet.
|
|
311
|
-
*/
|
|
312
|
-
interface SandboxListPage {
|
|
313
|
-
sandboxes: SandboxInfo[];
|
|
314
|
-
complete: boolean;
|
|
315
|
-
pagesFetched: number;
|
|
316
|
-
error?: string;
|
|
317
|
-
}
|
|
318
|
-
/**
|
|
319
|
-
* Sandboxes a single enumeration will walk before it gives up and reports
|
|
320
|
-
* itself incomplete. Modal's list is an async generator with no page size we
|
|
321
|
-
* control, so the ceiling is counted in SANDBOXES rather than pages — same
|
|
322
|
-
* purpose as the other providers' page caps: never return a short list that
|
|
323
|
-
* reads like a whole one.
|
|
324
|
-
*/
|
|
325
|
-
declare const MODAL_MAX_LIST_SANDBOXES = 10000;
|
|
326
105
|
/** Command execution capabilities */
|
|
327
106
|
interface SandboxCommands {
|
|
328
107
|
/** Run command and wait for completion */
|
|
@@ -353,8 +132,6 @@ interface SandboxFiles {
|
|
|
353
132
|
readStream(path: string): Promise<ReadableStream<Uint8Array>>;
|
|
354
133
|
/** Write from stream */
|
|
355
134
|
writeStream(path: string, stream: ReadableStream<Uint8Array>): Promise<void>;
|
|
356
|
-
/** Upload a local file by path, streamed off disk (never buffered whole) */
|
|
357
|
-
writeFromPath(sandboxPath: string, localPath: string): Promise<void>;
|
|
358
135
|
/** Get pre-signed upload URL for large files (expiration in seconds) */
|
|
359
136
|
uploadUrl(path: string, expiresInSeconds?: number): Promise<string>;
|
|
360
137
|
/** Get pre-signed download URL for large files (expiration in seconds) */
|
|
@@ -392,17 +169,12 @@ interface SandboxInstance {
|
|
|
392
169
|
interface SandboxProvider {
|
|
393
170
|
/** Provider type identifier */
|
|
394
171
|
readonly providerType: string;
|
|
395
|
-
/** Human-readable provider name for logging */
|
|
396
|
-
readonly name?: string;
|
|
397
172
|
/** Create new sandbox */
|
|
398
173
|
create(options: SandboxCreateOptions): Promise<SandboxInstance>;
|
|
399
174
|
/** Connect to existing sandbox */
|
|
400
175
|
connect(sandboxId: string, timeoutMs?: number): Promise<SandboxInstance>;
|
|
401
176
|
/** List sandboxes (first page only, up to limit) */
|
|
402
|
-
/** List sandboxes, walking the whole app. `limit` bounds items returned. */
|
|
403
177
|
list(options?: SandboxListOptions): Promise<SandboxInfo[]>;
|
|
404
|
-
/** The same enumeration for fleet bookkeeping: never throws, reports completeness. */
|
|
405
|
-
listAll(options?: SandboxListOptions): Promise<SandboxListPage>;
|
|
406
178
|
}
|
|
407
179
|
interface ModalConfig {
|
|
408
180
|
/** Modal app name. Default: "evolve-sandbox" */
|
|
@@ -415,15 +187,8 @@ interface ModalConfig {
|
|
|
415
187
|
tokenSecret?: string;
|
|
416
188
|
/** Modal API endpoint. Default: https://api.modal.com:443 */
|
|
417
189
|
endpoint?: string;
|
|
418
|
-
/** Docker image name (default: 'evolve-all
|
|
190
|
+
/** Docker image name (default: 'evolve-all'). Resolved through IMAGE_MAP or used as-is for custom images. */
|
|
419
191
|
imageName?: string;
|
|
420
|
-
/**
|
|
421
|
-
* Name of a Modal Secret holding registry credentials for private images.
|
|
422
|
-
* Required for AWS ECR (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
|
|
423
|
-
* AWS_REGION with read-only ECR IAM) and GCP Artifact Registry; optional
|
|
424
|
-
* for private Docker Hub images. Create one at https://modal.com/secrets
|
|
425
|
-
*/
|
|
426
|
-
imageSecretName?: string;
|
|
427
192
|
}
|
|
428
193
|
/** Internal resolved config with required credentials */
|
|
429
194
|
interface ResolvedModalConfig {
|
|
@@ -433,64 +198,6 @@ interface ResolvedModalConfig {
|
|
|
433
198
|
defaultTimeoutMs?: number;
|
|
434
199
|
endpoint?: string;
|
|
435
200
|
imageName?: string;
|
|
436
|
-
imageSecretName?: string;
|
|
437
|
-
}
|
|
438
|
-
declare class ModalCommands implements SandboxCommands {
|
|
439
|
-
private sandbox;
|
|
440
|
-
private user;
|
|
441
|
-
constructor(sandbox: Sandbox, user: string);
|
|
442
|
-
run(command: string, options?: SandboxRunOptions): Promise<SandboxCommandResult>;
|
|
443
|
-
spawn(command: string, options?: SandboxSpawnOptions): Promise<SandboxCommandHandle>;
|
|
444
|
-
list(): Promise<ProcessInfo[]>;
|
|
445
|
-
connect(_processId: string, _options?: SandboxConnectOptions): Promise<SandboxCommandHandle>;
|
|
446
|
-
sendStdin(_processId: string, _data: string): Promise<void>;
|
|
447
|
-
kill(processId: string): Promise<boolean>;
|
|
448
|
-
/**
|
|
449
|
-
* Accumulate stdout/stderr using for-await pattern (more reliable with Modal streams).
|
|
450
|
-
* Based on vibekit's approach which works correctly with Modal SDK.
|
|
451
|
-
*/
|
|
452
|
-
private accumulateStreams;
|
|
453
|
-
}
|
|
454
|
-
declare class ModalFiles implements SandboxFiles {
|
|
455
|
-
private sandbox;
|
|
456
|
-
private user;
|
|
457
|
-
constructor(sandbox: Sandbox, user: string);
|
|
458
|
-
/**
|
|
459
|
-
* Chown a path to the sandbox user so agent CLIs (running via the su
|
|
460
|
-
* wrapper) can access files created by root-level exec. No-op when the
|
|
461
|
-
* sandbox user is root.
|
|
462
|
-
*/
|
|
463
|
-
private chownToUser;
|
|
464
|
-
/**
|
|
465
|
-
* Write a payload to a process's stdin in MODAL_STDIN_CHUNK_BYTES slices.
|
|
466
|
-
* Each writeBytes() call becomes one gRPC TaskExecStdinWrite message and
|
|
467
|
-
* Modal rejects messages over 100MiB, so large files must be chunked
|
|
468
|
-
* (multi-hundred-MB payloads are common).
|
|
469
|
-
*/
|
|
470
|
-
private writeStdinChunked;
|
|
471
|
-
read(path: string): Promise<string | Uint8Array>;
|
|
472
|
-
write(path: string, content: string | Buffer | ArrayBuffer | Uint8Array): Promise<void>;
|
|
473
|
-
writeBatch(files: Array<{
|
|
474
|
-
path: string;
|
|
475
|
-
data: string | Buffer | ArrayBuffer | Uint8Array;
|
|
476
|
-
}>): Promise<void>;
|
|
477
|
-
makeDir(path: string): Promise<void>;
|
|
478
|
-
exists(path: string): Promise<boolean>;
|
|
479
|
-
list(path: string): Promise<FileInfo[]>;
|
|
480
|
-
remove(path: string): Promise<void>;
|
|
481
|
-
rename(oldPath: string, newPath: string): Promise<void>;
|
|
482
|
-
readStream(path: string): Promise<ReadableStream<Uint8Array>>;
|
|
483
|
-
writeStream(path: string, stream: ReadableStream<Uint8Array>): Promise<void>;
|
|
484
|
-
/**
|
|
485
|
-
* Upload a local file by PATH, chunk by chunk into the same `cat >` sink
|
|
486
|
-
* writeStream() uses — so peak memory is one chunk rather than the whole
|
|
487
|
-
* file, which is what makes a large artifact safe under concurrency.
|
|
488
|
-
*/
|
|
489
|
-
writeFromPath(sandboxPath: string, localPath: string): Promise<void>;
|
|
490
|
-
uploadUrl(_path: string, _expiresInSeconds?: number): Promise<string>;
|
|
491
|
-
downloadUrl(_path: string, _expiresInSeconds?: number): Promise<string>;
|
|
492
|
-
watchDir(_path: string, _onEvent: (event: FilesystemEvent) => void | Promise<void>, _options?: WatchOptions): Promise<WatchHandle>;
|
|
493
|
-
private toBuffer;
|
|
494
201
|
}
|
|
495
202
|
declare class ModalProvider implements SandboxProvider {
|
|
496
203
|
readonly providerType: "modal";
|
|
@@ -499,103 +206,13 @@ declare class ModalProvider implements SandboxProvider {
|
|
|
499
206
|
private readonly appName;
|
|
500
207
|
private readonly defaultTimeoutMs;
|
|
501
208
|
private readonly imageName;
|
|
502
|
-
private readonly imageSecretName?;
|
|
503
209
|
private _app;
|
|
504
|
-
/**
|
|
505
|
-
* Sandbox user configured at create time, reapplied on connect() so the su
|
|
506
|
-
* wrapper keeps targeting the same account. In-memory only: a connect()
|
|
507
|
-
* from a fresh process falls back to the default "user" account — callers
|
|
508
|
-
* reconnecting across processes must recreate the provider and sandbox with
|
|
509
|
-
* the same user, or operations on user-owned files fail loudly.
|
|
510
|
-
*/
|
|
511
|
-
private readonly sandboxUsers;
|
|
512
210
|
constructor(config: ResolvedModalConfig);
|
|
513
211
|
private getApp;
|
|
514
|
-
/**
|
|
515
|
-
* Build a Modal Image for the resolved tag, routing private registries
|
|
516
|
-
* (AWS ECR, GCP Artifact Registry) through the configured Modal Secret.
|
|
517
|
-
*/
|
|
518
|
-
private resolveImage;
|
|
519
212
|
create(options: SandboxCreateOptions): Promise<SandboxInstance>;
|
|
520
213
|
connect(sandboxId: string, _timeoutMs?: number): Promise<SandboxInstance>;
|
|
521
|
-
|
|
522
|
-
* List sandboxes, walking the whole app.
|
|
523
|
-
*
|
|
524
|
-
* This used to stop at a hardcoded default of 100 regardless of fleet size,
|
|
525
|
-
* which silently truncated any app with more — and said nothing about it
|
|
526
|
-
* while the shared SandboxProvider interface promised exhaustive listing.
|
|
527
|
-
* `limit` still bounds the sandboxes RETURNED, so a caller wanting one cheap
|
|
528
|
-
* sample asks for one; without it the answer is the whole app.
|
|
529
|
-
*
|
|
530
|
-
* The O(N)-round-trips warning below is unchanged and is the reason `limit`
|
|
531
|
-
* matters here more than on the other providers.
|
|
532
|
-
*/
|
|
533
|
-
list(options?: SandboxListOptions): Promise<SandboxInfo[]>;
|
|
534
|
-
/**
|
|
535
|
-
* The fleet-bookkeeping enumeration: same walk, never throws.
|
|
536
|
-
*
|
|
537
|
-
* Modal has no lifecycle webhooks, so absence from a list is the ONLY
|
|
538
|
-
* termination signal either lane gets — which makes the difference between
|
|
539
|
-
* "the app is empty" and "the enumeration stopped early" the difference
|
|
540
|
-
* between a quiet fleet and one about to be reclaimed.
|
|
541
|
-
*
|
|
542
|
-
* NOTE the divergence from `listSandboxIds` below, which returns an EMPTY set
|
|
543
|
-
* on failure on the grounds that partial results are worse than none for a
|
|
544
|
-
* terminal-state decision. This one returns what it saw alongside
|
|
545
|
-
* `complete: false`. Both are safe because `complete` is what callers branch
|
|
546
|
-
* on, and the shared type documents the choice; do not align one to the other
|
|
547
|
-
* without deciding which rule you want.
|
|
548
|
-
*/
|
|
549
|
-
listAll(options?: SandboxListOptions): Promise<SandboxListPage>;
|
|
550
|
-
private walk;
|
|
551
|
-
/**
|
|
552
|
-
* Live sandbox ids for the whole app, in ONE streamed call and O(1) round
|
|
553
|
-
* trips — the fleet-bookkeeping counterpart to `list()`.
|
|
554
|
-
*
|
|
555
|
-
* Exists because `list()` cannot be made cheap without dropping metadata from
|
|
556
|
-
* its contract: it owes callers a populated `SandboxInfo.metadata`, and Modal
|
|
557
|
-
* only serves tags per sandbox. Anything that just needs "which ids are
|
|
558
|
-
* alive" — lifecycle polling, orphan sweeps, reconciliation — uses this and
|
|
559
|
-
* pays one request no matter how large the fleet is.
|
|
560
|
-
*
|
|
561
|
-
* `complete` is the load-bearing field, not a nicety: absence from this list
|
|
562
|
-
* is what callers read as "terminated", so a truncated or errored enumeration
|
|
563
|
-
* MUST NOT be mistaken for an empty fleet. A caller that sees complete=false
|
|
564
|
-
* has to leave rows alone rather than mass-marking live sandboxes dead.
|
|
565
|
-
*/
|
|
566
|
-
listSandboxIds(): Promise<{
|
|
567
|
-
ids: Set<string>;
|
|
568
|
-
complete: boolean;
|
|
569
|
-
}>;
|
|
214
|
+
list(_options?: SandboxListOptions): Promise<SandboxInfo[]>;
|
|
570
215
|
}
|
|
571
|
-
/** The streamed sandbox surface this walk needs — Modal's list() satisfies it. */
|
|
572
|
-
interface ModalSandboxStream {
|
|
573
|
-
sandboxId: string;
|
|
574
|
-
getTags(): Promise<Record<string, string>>;
|
|
575
|
-
}
|
|
576
|
-
/**
|
|
577
|
-
* Drain Modal's sandbox generator into one answer, with an honest completeness
|
|
578
|
-
* verdict.
|
|
579
|
-
*
|
|
580
|
-
* Separate from the provider because everything worth getting wrong lives here
|
|
581
|
-
* and none of it needs a gRPC connection: the difference between "the caller
|
|
582
|
-
* asked for ten" and "the app ran out", the ceiling that stops an unbounded
|
|
583
|
-
* walk, and the rule that a failure mid-walk yields what it saw marked
|
|
584
|
-
* INCOMPLETE rather than an exception or a short complete list.
|
|
585
|
-
*
|
|
586
|
-
* COST WARNING — this loop is O(N) ROUND TRIPS, not O(1). `list()` itself is one
|
|
587
|
-
* streamed call, but `getTags()` is a separate gRPC request per sandbox
|
|
588
|
-
* (`sandboxTagsGet`), so listing N sandboxes costs N+1 calls. That is fine for a
|
|
589
|
-
* user listing their handful of boxes with metadata, and NOT fine for fleet-wide
|
|
590
|
-
* bookkeeping: anything that only needs to know WHICH ids are alive must use
|
|
591
|
-
* `listSandboxIds`, never this. Please do not "optimize" by reintroducing tag
|
|
592
|
-
* reads into those paths.
|
|
593
|
-
*
|
|
594
|
-
* Exported for its test (`_testCollectSandboxes`).
|
|
595
|
-
*/
|
|
596
|
-
declare function collectSandboxes(iterate: () => AsyncIterable<ModalSandboxStream>, wanted?: number): Promise<SandboxListPage & {
|
|
597
|
-
stoppedAtLimit: boolean;
|
|
598
|
-
}>;
|
|
599
216
|
/**
|
|
600
217
|
* Create Modal sandbox provider.
|
|
601
218
|
*
|
|
@@ -605,14 +222,5 @@ declare function collectSandboxes(iterate: () => AsyncIterable<ModalSandboxStrea
|
|
|
605
222
|
* @see https://github.com/evolving-machines-lab/evolve/issues/8
|
|
606
223
|
*/
|
|
607
224
|
declare function createModalProvider(config?: ModalConfig): SandboxProvider;
|
|
608
|
-
declare const _testWrapCommand: typeof wrapCommand;
|
|
609
|
-
declare const _testImageMap: Record<string, string>;
|
|
610
|
-
declare const _testMapNetworkPolicy: typeof mapNetworkPolicy;
|
|
611
|
-
declare const _testMapResources: typeof mapResources;
|
|
612
|
-
declare const _testResolveImageRegistry: typeof resolveImageRegistry;
|
|
613
|
-
declare const _testBuildSandboxInfo: typeof buildSandboxInfo;
|
|
614
|
-
declare const _testCollectSandboxes: typeof collectSandboxes;
|
|
615
|
-
declare const _testValidateTimeout: typeof validateTimeout;
|
|
616
|
-
declare const _testMapIdleTimeout: typeof mapIdleTimeout;
|
|
617
225
|
|
|
618
|
-
export {
|
|
226
|
+
export { type FileInfo, type FilesystemEvent, type ModalConfig, ModalProvider, type ProcessInfo, type SandboxCommandHandle, type SandboxCommandResult, type SandboxCommands, type SandboxConnectOptions, type SandboxCreateOptions, type SandboxFiles, type SandboxInfo, type SandboxInstance, type SandboxListOptions, type SandboxProvider, type SandboxRunOptions, type SandboxSpawnOptions, type WatchHandle, type WatchOptions, createModalProvider };
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {ModalClient}from'modal';import {pack}from'tar-stream';var
|
|
2
|
-
`).slice(1).map(
|
|
3
|
-
`)){if(!
|
|
4
|
-
export{
|
|
1
|
+
import {ModalClient}from'modal';import {pack}from'tar-stream';var b={"evolve-all":"evolvingmachines/evolve-all"},h=new Set([".xlsx",".xls",".docx",".doc",".pptx",".ppt",".pdf",".zip",".tar",".gz",".7z",".rar",".png",".jpg",".jpeg",".gif",".webp",".ico",".bmp",".mp3",".wav",".ogg",".flac",".aac",".mp4",".avi",".mov",".mkv",".webm",".woff",".woff2",".ttf",".otf",".eot",".exe",".dll",".so",".dylib",".sqlite",".db",".pickle",".pkl",".parquet"]);function y(c){let t=c.substring(c.lastIndexOf(".")).toLowerCase();return h.has(t)}var u=class{constructor(t){this.sandbox=t;}wrapAsUser(t,e,n){let r="";n&&Object.keys(n).length>0&&(r=Object.entries(n).filter(([,o])=>o!=null).map(([o,i])=>`export ${o}='${String(i).replace(/'/g,"'\\''")}'`).join("; ")+"; ");let s=e?`cd '${e.replace(/'/g,"'\\''")}' && ${r}${t}`:`${r}${t}`;return ["su","user","-c",`echo ${Buffer.from(s).toString("base64")} | base64 -d | bash`]}async run(t,e){let n=this.wrapAsUser(t,e?.cwd,e?.envs),r=await this.sandbox.exec(n,{timeoutMs:e?.timeoutMs}),{stdout:s,stderr:a}=await this.accumulateStreams(r,e?.onStdout,e?.onStderr);return {exitCode:await r.wait(),stdout:s,stderr:a}}async spawn(t,e){let n=this.wrapAsUser(t,e?.cwd,e?.envs),r=await this.sandbox.exec(n,{timeoutMs:e?.timeoutMs}),s="",a="",o=this.accumulateStreams(r,e?.onStdout?d=>{e.onStdout(d);}:void 0,e?.onStderr?d=>{e.onStderr(d);}:void 0).then(({stdout:d,stderr:m})=>{s=d,a=m;}).catch(()=>{});return {processId:`modal-${Date.now()}-${Math.random().toString(36).slice(2)}`,wait:async()=>(await o,{exitCode:await r.wait(),stdout:s,stderr:a}),kill:async()=>false}}async list(){let t=await this.sandbox.exec(["ps","-eo","pid,comm,args"],{timeoutMs:1e4});return await t.wait(),(await t.stdout.readText()).trim().split(`
|
|
2
|
+
`).slice(1).map(r=>{let s=r.trim().split(/\s+/);return {processId:s[0],cmd:s[1]||"",args:s.slice(2),envs:{}}})}async connect(t,e){throw new Error("Modal does not support connecting to existing processes")}async sendStdin(t,e){throw new Error("Modal does not support sendStdin by process ID")}async kill(t){return await(await this.sandbox.exec(["kill","-9",t],{timeoutMs:1e4})).wait()===0}async accumulateStreams(t,e,n){let r="",s="",a=[];return a.push((async()=>{try{for await(let o of t.stdout){let i=typeof o=="string"?o:new TextDecoder().decode(o);r+=i,e?.(i);}}catch{}})()),a.push((async()=>{try{for await(let o of t.stderr){let i=typeof o=="string"?o:new TextDecoder().decode(o);s+=i,n?.(i);}}catch{}})()),await Promise.all(a),{stdout:r,stderr:s}}},g=class{constructor(t){this.sandbox=t;}async read(t){if(y(t)){let r=await this.sandbox.exec(["cat",t],{timeoutMs:3e5,mode:"binary"}),s=await r.wait();if(s!==0){let a=await r.stderr.readText();throw new Error(`Failed to read file ${t}: ${a||`exit code ${s}`}`)}return await r.stdout.readBytes()}let e=await this.sandbox.exec(["cat",t],{timeoutMs:3e5}),n=await e.wait();if(n!==0){let r=await e.stderr.readText();throw new Error(`Failed to read file ${t}: ${r||`exit code ${n}`}`)}return await e.stdout.readText()}async write(t,e){let n=this.toBuffer(e),r=t.substring(0,t.lastIndexOf("/"));r&&await this.makeDir(r);let s=t.replace(/'/g,"'\\''"),a=await this.sandbox.exec(["bash","-c",`cat > '${s}'`],{mode:"binary"});await a.stdin.writeBytes(new Uint8Array(n)),await a.stdin.getWriter().close(),await a.wait(),await(await this.sandbox.exec(["chown","user:user",t],{timeoutMs:1e4})).wait();}async writeBatch(t){let e=pack(),n=[],r=new Set;for(let i of t){let d=this.toBuffer(i.data),m=i.path.startsWith("/")?i.path.slice(1):i.path;e.entry({name:m},d);let p=i.path.substring(0,i.path.lastIndexOf("/"));p&&r.add(p);}e.finalize();for await(let i of e)n.push(Buffer.from(i));let s=Buffer.concat(n),a=await this.sandbox.exec(["tar","-xf","-","-C","/"],{mode:"binary"});if(await a.stdin.writeBytes(new Uint8Array(s)),await a.stdin.getWriter().close(),await a.wait(),r.size>0){let i=Array.from(r),d=new Set(i.map(m=>m.split("/").slice(0,4).join("/")));for(let m of d)await(await this.sandbox.exec(["chown","-R","user:user",m],{timeoutMs:3e4})).wait();}}async makeDir(t){await(await this.sandbox.exec(["mkdir","-p",t],{timeoutMs:1e4})).wait(),await(await this.sandbox.exec(["chown","-R","user:user",t],{timeoutMs:1e4})).wait();}async exists(t){return await(await this.sandbox.exec(["test","-e",t],{timeoutMs:1e4})).wait()===0}async list(t){let e=t.replace(/'/g,"'\\''"),n=await this.sandbox.exec(["bash","-c",`ls -la '${e}' | tail -n +2`],{timeoutMs:3e4});await n.wait();let r=await n.stdout.readText(),s=[];for(let a of r.trim().split(`
|
|
3
|
+
`)){if(!a)continue;let o=a.split(/\s+/);if(o.length<9)continue;let i=o[0],d=o.slice(8).join(" ");d==="."||d===".."||s.push({name:d,path:t.endsWith("/")?`${t}${d}`:`${t}/${d}`,type:i.startsWith("d")?"dir":"file"});}return s}async remove(t){await(await this.sandbox.exec(["rm","-rf",t],{timeoutMs:3e4})).wait();}async rename(t,e){await(await this.sandbox.exec(["mv",t,e],{timeoutMs:3e4})).wait();}async readStream(t){return (await this.sandbox.exec(["cat",t],{timeoutMs:3e5,mode:"binary"})).stdout}async writeStream(t,e){let n=t.substring(0,t.lastIndexOf("/"));n&&await this.makeDir(n);let r=t.replace(/'/g,"'\\''"),s=await this.sandbox.exec(["bash","-c",`cat > '${r}'`],{mode:"binary"}),a=e.getReader();try{for(;;){let{done:i,value:d}=await a.read();if(i)break;await s.stdin.writeBytes(d);}}finally{a.releaseLock();}await s.stdin.getWriter().close(),await s.wait();}async uploadUrl(t,e){throw new Error("Modal does not support pre-signed upload URLs")}async downloadUrl(t,e){throw new Error("Modal does not support pre-signed download URLs")}async watchDir(t,e,n){throw new Error("Modal does not support watchDir")}toBuffer(t){if(typeof t=="string")return Buffer.from(t,"utf-8");if(t instanceof Buffer)return t;if(t instanceof ArrayBuffer||t instanceof Uint8Array)return Buffer.from(t);throw new Error(`Unsupported data type: ${typeof t}`)}},l=class{constructor(t,e){this.sandbox=t;this.commands=new u(t),this.files=new g(t),this.image=e,this.startTime=new Date;}commands;files;image;startTime;get sandboxId(){return this.sandbox.sandboxId}async getHost(t){let n=(await this.sandbox.tunnels())[t];if(!n)throw new Error(`No tunnel found for port ${t}`);return n.url}async isRunning(){try{return await(await this.sandbox.exec(["echo","ping"],{timeoutMs:5e3})).wait(),!0}catch{return false}}async getInfo(){return {sandboxId:this.sandbox.sandboxId,image:this.image,metadata:{},startedAt:this.startTime.toISOString()}}async kill(){try{await this.sandbox.terminate();}catch{await new Promise(t=>setTimeout(t,500)),await this.sandbox.terminate();}}async pause(){throw new Error("Modal does not support pause. Use kill() instead.")}},w=class{providerType="modal";name="Modal";client;appName;defaultTimeoutMs;imageName;_app;constructor(t){!t.endpoint&&process.env.MODAL_SERVER_URL?.startsWith("unix:")?process.env.MODAL_SERVER_URL="https://api.modal.com:443":t.endpoint&&(process.env.MODAL_SERVER_URL=t.endpoint),this.client=new ModalClient({tokenId:t.tokenId,tokenSecret:t.tokenSecret}),this.appName=t.appName??"evolve-sandbox",this.defaultTimeoutMs=t.defaultTimeoutMs??36e5,this.imageName=t.imageName??"evolve-all";}async getApp(){return this._app||(this._app=await this.client.apps.fromName(this.appName,{createIfMissing:true})),this._app}async create(t){let e=await this.getApp(),n=t.timeoutMs??this.defaultTimeoutMs,r=t.image||this.imageName,s=b[r]??r,o=await this.client.images.fromRegistry(s).build(e),i=t.envs?Object.fromEntries(Object.entries(t.envs).filter(([,p])=>p!=null)):void 0,d=i&&Object.keys(i).length>0?i:void 0,m=await this.client.sandboxes.create(e,o,{cpu:4,memoryMiB:4096,timeoutMs:n,workdir:t.workingDirectory,env:d});return t.workingDirectory&&await(await m.exec(["chown","-R","user:user",t.workingDirectory],{timeoutMs:3e4})).wait(),new l(m,s)}async connect(t,e){let n=await this.client.sandboxes.fromId(t);return new l(n,"unknown")}async list(t){let e=[],n=t?.limit??100;try{for await(let r of this.client.sandboxes.list())if(e.push({sandboxId:r.sandboxId,image:"unknown",metadata:{},startedAt:new Date().toISOString()}),e.length>=n)break}catch{}return e}};function k(c={}){let t=c.tokenId??process.env.MODAL_TOKEN_ID,e=c.tokenSecret??process.env.MODAL_TOKEN_SECRET;if(!t||!e)throw new Error("Modal credentials required. Set MODAL_TOKEN_ID and MODAL_TOKEN_SECRET environment variables, or pass tokenId/tokenSecret in config. Get your token at https://modal.com/settings/tokens");return new w({...c,tokenId:t,tokenSecret:e})}
|
|
4
|
+
export{w as ModalProvider,k as createModalProvider};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@evolvingmachines/modal",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.53",
|
|
4
4
|
"keywords": [
|
|
5
5
|
"ai",
|
|
6
6
|
"agents",
|
|
@@ -33,11 +33,10 @@
|
|
|
33
33
|
"scripts": {
|
|
34
34
|
"build": "tsup --minify",
|
|
35
35
|
"dev": "tsup --watch",
|
|
36
|
-
"type-check": "tsc --noEmit"
|
|
37
|
-
"test:unit": "tsx tests/unit/modal-provider.test.ts && tsx tests/unit/modal-list-pagination.test.ts"
|
|
36
|
+
"type-check": "tsc --noEmit"
|
|
38
37
|
},
|
|
39
38
|
"dependencies": {
|
|
40
|
-
"modal": "^0.
|
|
39
|
+
"modal": "^0.6.0",
|
|
41
40
|
"tar-stream": "^3.1.7"
|
|
42
41
|
},
|
|
43
42
|
"devDependencies": {
|